@synapta/skills 0.1.0 → 0.1.2

package/skills/deploy-k8s/references/insecure-workload-defaults.md

@@ -0,0 +1,300 @@
+# Insecure Workload Defaults
+
+**USE THIS GUIDE** when generating or reviewing any Kubernetes workload manifest
+(Deployment, StatefulSet, DaemonSet, Job, CronJob, or bare Pod).
+Default security posture: **PSS "restricted" profile** unless the user explicitly
+requests otherwise and provides justification.
+
+---
+
+## Symptoms
+
+- Containers running as root (UID 0) inside the cluster.
+- Pods admitted without any `securityContext` at all.
+- Linux capabilities not dropped, leaving `CAP_NET_RAW`, `CAP_SYS_ADMIN`, etc.
+- `hostPath` volumes mounted into workload pods.
+- Privileged containers that can escape to the node.
+- PodSecurity admission webhook rejecting manifests at deploy time.
+- CVE exploitation amplified by overly permissive container runtime settings.
+
+---
+
+## Root Causes
+
+1. Upstream example manifests and Helm chart defaults rarely include security contexts.
+2. LLMs train on those same permissive examples and reproduce them verbatim.
+3. `securityContext` has both pod-level and container-level fields; omitting either leaves gaps.
+4. Teams copy "it works in dev" manifests into production without hardening.
+5. Confusion between PSS levels (privileged, baseline, restricted) leads to the wrong choice.
+
+---
+
+## Pod Security Standards Quick Reference
+
+| Level        | When to use                                                        |
+|--------------|--------------------------------------------------------------------|
+| `restricted` | **Default for all workloads.** Enforces non-root, drops caps, etc. |
+| `baseline`   | Minimum acceptable floor. Use only when restricted is impossible.  |
+| `privileged` | CNI plugins, storage drivers, node-level agents. Never for apps.   |
+
+Label namespaces to enforce:
+
+```yaml
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: production
+  labels:
+    pod-security.kubernetes.io/enforce: restricted
+    pod-security.kubernetes.io/audit: restricted
+    pod-security.kubernetes.io/warn: restricted
+```
+
+---
+
+## Prevention Rules
+
+### Container Security Context Baseline
+
+Every container MUST include this block unless a specific, documented deviation is required:
+
+```yaml
+securityContext:
+  runAsNonRoot: true
+  allowPrivilegeEscalation: false
+  readOnlyRootFilesystem: true
+  capabilities:
+    drop:
+      - ALL
+  seccompProfile:
+    type: RuntimeDefault
+```
+
+### Pod-Level vs Container-Level Security Context
+
+Pod-level fields apply to ALL containers including init containers:
+
+```yaml
+spec:
+  securityContext:            # Pod-level
+    runAsNonRoot: true
+    runAsUser: 10000
+    runAsGroup: 10000
+    fsGroup: 10000
+    seccompProfile:
+      type: RuntimeDefault
+  containers:
+    - name: app
+      securityContext:        # Container-level (overrides/supplements pod-level)
+        allowPrivilegeEscalation: false
+        readOnlyRootFilesystem: true
+        capabilities:
+          drop:
+            - ALL
+```
+
+Key distinctions:
+- `runAsUser`, `runAsGroup`, `fsGroup`, `seccompProfile` belong at pod level.
+- `allowPrivilegeEscalation`, `readOnlyRootFilesystem`, `capabilities` belong at container level.
+- `runAsNonRoot` can be set at either level; pod level is preferred for consistency.
+
+### When Deviations Are Acceptable
+
+Init containers sometimes need narrow capabilities. Always document the reason:
+
+```yaml
+initContainers:
+  - name: fix-permissions
+    # DEVIATION: requires CAP_CHOWN to set volume ownership before app starts.
+    # Pod-level runAsNonRoot is still true; this container runs as root briefly.
+    securityContext:
+      runAsNonRoot: false
+      runAsUser: 0
+      allowPrivilegeEscalation: false
+      readOnlyRootFilesystem: true
+      capabilities:
+        drop:
+          - ALL
+        add:
+          - CHOWN
+```
+
+### Host Namespace Access
+
+These fields MUST be `false` (or omitted, since false is the default) for application workloads:
+
+```yaml
+spec:
+  hostNetwork: false   # Exposes pod to node network stack
+  hostPID: false       # Allows seeing all node processes
+  hostIPC: false       # Allows shared memory with node processes
+  hostUsers: false     # Maps to host user namespace (k8s 1.28+)
+```
+
+### AppArmor and Seccomp
+
+Seccomp `RuntimeDefault` is mandatory under PSS restricted. For additional confinement:
+
+```yaml
+metadata:
+  annotations:
+    # AppArmor (becomes a first-class field in k8s 1.30+)
+    container.apparmor.security.beta.kubernetes.io/app: runtime/default
+spec:
+  securityContext:
+    seccompProfile:
+      type: RuntimeDefault    # Or Localhost with a custom profile
+```
+
+---
+
+## Patterns
+
+### GOOD: Production Deployment with Full Security Hardening
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: api-server
+  namespace: production
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: api-server
+  template:
+    metadata:
+      labels:
+        app: api-server
+    spec:
+      automountServiceAccountToken: false
+      securityContext:
+        runAsNonRoot: true
+        runAsUser: 10000
+        runAsGroup: 10000
+        fsGroup: 10000
+        seccompProfile:
+          type: RuntimeDefault
+      containers:
+        - name: api
+          image: registry.example.com/api-server:v2.4.1@sha256:abc123...
+          ports:
+            - containerPort: 8080
+              protocol: TCP
+          securityContext:
+            allowPrivilegeEscalation: false
+            readOnlyRootFilesystem: true
+            capabilities:
+              drop:
+                - ALL
+          volumeMounts:
+            - name: tmp
+              mountPath: /tmp
+            - name: cache
+              mountPath: /var/cache/app
+          resources:
+            requests:
+              cpu: 100m
+              memory: 128Mi
+            limits:
+              memory: 256Mi
+      serviceAccountName: api-server
+      volumes:
+        - name: tmp
+          emptyDir:
+            sizeLimit: 64Mi
+        - name: cache
+          emptyDir:
+            sizeLimit: 128Mi
+```
+
+### BAD: Typical LLM-Generated Deployment (Missing All Controls)
+
+```yaml
+# INSECURE - DO NOT USE
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: api-server
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: api-server
+  template:
+    metadata:
+      labels:
+        app: api-server
+    spec:
+      containers:
+        - name: api
+          image: api-server:latest          # No registry, mutable tag, no digest
+          ports:
+            - containerPort: 8080
+          # No securityContext at all
+          # No resource requests or limits
+          # No readOnlyRootFilesystem
+          # Capabilities not dropped
+          # automountServiceAccountToken defaults to true
+```
+
+Problems with the bad example:
+1. No pod-level or container-level `securityContext` -- runs as root.
+2. `image: api-server:latest` -- mutable tag, no registry prefix, no digest pinning.
+3. No `resources` -- becomes BestEffort QoS, first to be evicted.
+4. Default service account token mounted -- unnecessary API access.
+5. Missing `namespace` -- deploys to whatever context is active.
+6. Single replica -- no availability guarantee.
+7. No `readOnlyRootFilesystem` -- writable container filesystem aids attackers.
+8. Capabilities not dropped -- container retains default Linux capabilities.
+
+---
+
+## LLM Mistake Checklist
+
+Before emitting any workload manifest, verify every item:
+
+- [ ] **securityContext present at BOTH pod and container level** -- not just one.
+- [ ] **`runAsNonRoot: true`** set at pod level (not just assumed from the image).
+- [ ] **`allowPrivilegeEscalation: false`** on every container including init containers.
+- [ ] **`capabilities.drop: [ALL]`** on every container -- never omitted, never partial.
+- [ ] **`readOnlyRootFilesystem: true`** with `emptyDir` mounts for `/tmp` and write paths.
+- [ ] **`seccompProfile.type: RuntimeDefault`** at pod level.
+- [ ] **`automountServiceAccountToken: false`** unless the workload calls the Kubernetes API.
+- [ ] **Image uses a digest or immutable tag** -- never `:latest` or bare image names.
+- [ ] **No `hostPath` volumes** unless explicitly requested with justification.
+- [ ] **No `hostNetwork`, `hostPID`, `hostIPC`** unless explicitly requested.
+- [ ] **No `privileged: true`** unless explicitly requested for infrastructure components.
+- [ ] **`runAsUser`/`runAsGroup` set to non-zero values** -- do not leave them unset.
+
+---
+
+## Verification Commands
+
+```bash
+# Check if a manifest passes PSS restricted validation (dry-run)
+kubectl apply --dry-run=server -f manifest.yaml
+
+# Inspect running pod security contexts
+kubectl get pod <pod> -o jsonpath='{.spec.securityContext}' | jq .
+kubectl get pod <pod> -o jsonpath='{.spec.containers[*].securityContext}' | jq .
+
+# Validate manifest schema
+kubeconform -strict -kubernetes-version 1.30.0 manifest.yaml
+
+# Scan with kubesec (static analysis)
+kubesec scan manifest.yaml
+
+# Check namespace PSS enforcement labels
+kubectl get namespace <ns> -o jsonpath='{.metadata.labels}' | jq .
+
+# Audit running workloads for security issues
+kubectl get pods -A -o json | jq '.items[] | select(.spec.containers[].securityContext.runAsNonRoot != true) | .metadata.name'
+
+# Check for privileged containers cluster-wide
+kubectl get pods -A -o json | jq '.items[] | select(.spec.containers[].securityContext.privileged == true) | "\(.metadata.namespace)/\(.metadata.name)"'
+
+# Verify no hostPath volumes in use
+kubectl get pods -A -o json | jq '.items[] | select(.spec.volumes[]?.hostPath != null) | "\(.metadata.namespace)/\(.metadata.name)"'
+```

package/skills/deploy-k8s/references/job-patterns.md

@@ -0,0 +1,120 @@
+# Job and CronJob Patterns -- Batch Processing
+
+**Load this reference when generating:** Job, CronJob, or any one-off / scheduled batch workload (migrations, ETL, reports, cleanup).
+
+## When to Use
+- **Job**: finite work that runs to completion. Database migrations, data exports, ML training, one-time scripts.
+- **CronJob**: recurring scheduled work. Report generation, cache warming, log rotation, periodic health checks.
+- If the workload runs indefinitely, use a Deployment (even for queue workers -- scale with HPA).
+
+## Job Configuration
+| Field | Purpose | Guidance |
+|---|---|---|
+| `completions` | Pods that must succeed | Default 1. Increase for fan-out. |
+| `parallelism` | Max concurrent pods | Default 1. Increase for parallelizable work. |
+| `backoffLimit` | Retries before failure | Default 6. Lower (2-3) for non-transient errors. |
+| `activeDeadlineSeconds` | Hard timeout | **Always set.** Prevents runaway jobs. |
+| `ttlSecondsAfterFinished` | Auto-cleanup delay | **Always set.** 3600 is a safe default. |
+
+## Completion Modes
+- **NonIndexed** (default): pods are interchangeable. Job succeeds after `completions` pods succeed.
+- **Indexed**: each pod gets `JOB_COMPLETION_INDEX` env var (0, 1, 2...). Use for partitioned/sharded work.
+
+## TTL After Finished
+Without `ttlSecondsAfterFinished`, finished Jobs and their pods accumulate forever. The TTL controller deletes the Job, pods, and logs -- ship logs externally if you need them longer.
+
+## CronJob Patterns
+
+**Schedule**: standard 5-field cron (`minute hour dom month dow`).
+**Timezone** (1.27+): `timeZone: "America/New_York"` pins to a specific tz instead of controller clock.
+
+**Concurrency policies**:
+| Policy | Behavior | Default to |
+|---|---|---|
+| `Allow` | Overlapping runs permitted | Avoid unless jobs are independent |
+| `Forbid` | Skip if previous still running | **Use this by default** |
+| `Replace` | Cancel running, start new | Only when latest run is all that matters |
+
+**startingDeadlineSeconds**: skip the run if more than N seconds late (prevents burst of overdue jobs after controller downtime).
+
+## Idempotency
+Jobs may retry (node failure, preemption). Every Job MUST be idempotent:
+- Upserts, not inserts. Check for already-completed work. Write to unique output locations.
+- Assume **at least once** execution, never exactly once.
+
+## Pod Failure Policy (1.26+)
+Handle different failures differently -- avoid retrying known-fatal errors:
+```yaml
+spec:
+  backoffLimit: 3
+  podFailurePolicy:
+    rules:
+      - action: FailJob
+        onExitCodes:
+          containerName: worker
+          operator: In
+          values: [1]               # bad config -- no point retrying
+      - action: Ignore
+        onPodConditions:
+          - type: DisruptionTarget  # node drain -- retry without counting
+```
+Actions: `FailJob` (fail immediately), `Count` (count toward backoffLimit), `Ignore` (retry free).
+
+## Example: Production CronJob
+```yaml
+apiVersion: batch/v1
+kind: CronJob
+metadata:
+  name: daily-report
+  labels: { app.kubernetes.io/name: daily-report, app.kubernetes.io/component: batch }
+spec:
+  schedule: "30 3 * * *"
+  timeZone: "UTC"
+  concurrencyPolicy: Forbid
+  startingDeadlineSeconds: 600
+  successfulJobsHistoryLimit: 3
+  failedJobsHistoryLimit: 5
+  jobTemplate:
+    metadata:
+      labels: { app.kubernetes.io/name: daily-report, app.kubernetes.io/component: batch }
+    spec:
+      ttlSecondsAfterFinished: 86400
+      activeDeadlineSeconds: 3600
+      backoffLimit: 2
+      template:
+        metadata:
+          labels: { app.kubernetes.io/name: daily-report, app.kubernetes.io/component: batch }
+        spec:
+          restartPolicy: Never
+          securityContext:
+            runAsNonRoot: true
+            runAsUser: 10000
+            runAsGroup: 10000
+            fsGroup: 10000
+            seccompProfile: { type: RuntimeDefault }
+          containers:
+            - name: report-generator
+              image: registry.example.com/daily-report:2.1.0
+              args: ["--date", "yesterday", "--output", "s3://reports/daily/"]
+              resources:
+                requests: { cpu: 500m, memory: 512Mi }
+                limits:   { cpu: "2", memory: 2Gi }
+              securityContext:
+                allowPrivilegeEscalation: false
+                readOnlyRootFilesystem: true
+                capabilities: { drop: ["ALL"] }
+              volumeMounts:
+                - { name: tmp, mountPath: /tmp }
+          volumes:
+            - { name: tmp, emptyDir: { sizeLimit: 1Gi } }
+```
+
+## LLM Mistake Checklist
+1. **Wrong restartPolicy.** Job pods MUST use `Never` or `OnFailure`. The default `Always` is rejected by the API.
+2. **Missing activeDeadlineSeconds.** A stuck Job without a deadline runs forever. Always set an upper bound.
+3. **Omitting ttlSecondsAfterFinished.** Completed Jobs accumulate indefinitely without this. Always set a TTL.
+4. **ConcurrencyPolicy defaulting to Allow.** Most CronJobs should use `Forbid`. Overlapping runs cause resource exhaustion and data corruption.
+5. **Labels missing on nested templates.** CronJobs have three label levels (CronJob, jobTemplate, pod template). All three need consistent labels.
+6. **Indexed Job ignoring JOB_COMPLETION_INDEX.** Setting `completionMode: Indexed` is useless if the container never reads the index env var.
+7. **Non-idempotent retried Jobs.** If `backoffLimit > 0`, the Job will retry. Inserts without upsert logic create duplicates.
+8. **Schedule without timeZone.** Without `timeZone`, the schedule uses the controller's clock (typically UTC). Set it explicitly if you mean a specific timezone.

package/skills/deploy-k8s/references/kustomize-patterns.md

@@ -0,0 +1,239 @@
+# Kustomize Patterns
+
+> When applying environment-specific customization or overlay-based configuration
+> to Kubernetes manifests, follow these patterns. Default security posture is PSS
+> "restricted" profile.
+
+---
+
+## Directory Structure
+
+```
+app/
+  base/
+    kustomization.yaml
+    deployment.yaml
+    service.yaml
+    namespace.yaml
+  overlays/
+    dev/
+      kustomization.yaml
+      replica-patch.yaml
+    staging/
+      kustomization.yaml
+    production/
+      kustomization.yaml
+      resource-patch.yaml
+      hpa.yaml
+  components/
+    monitoring/
+      kustomization.yaml
+      servicemonitor.yaml
+```
+
+## kustomization.yaml Required Fields
+
+```yaml
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources:
+  - deployment.yaml
+  - service.yaml
+```
+
+Every kustomization.yaml must declare `apiVersion`, `kind`, and `resources` (or `bases` in legacy usage, but prefer `resources`).
+
+## Common Transformers
+
+```yaml
+# Prefix/suffix all resource names
+namePrefix: prod-
+nameSuffix: -v2
+
+# Add labels to all resources and their selectors
+commonLabels:
+  app.kubernetes.io/part-of: my-platform
+  environment: production
+
+# Add annotations to all resources
+commonAnnotations:
+  team: platform-eng
+
+# Set namespace on all resources
+namespace: production
+```
+
+## Patches
+
+### Strategic Merge Patch
+
+Use when you want to merge into an existing structure. Good for adding or overriding specific fields.
+
+```yaml
+# kustomization.yaml
+patches:
+  - path: resource-patch.yaml
+
+# resource-patch.yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: my-app
+spec:
+  replicas: 3
+  template:
+    spec:
+      containers:
+        - name: my-app
+          resources:
+            requests:
+              cpu: 500m
+              memory: 512Mi
+            limits:
+              memory: 1Gi
+```
+
+### JSON Patch
+
+Use when you need to add, remove, or replace at a specific path. Required for array element manipulation.
+
+```yaml
+# kustomization.yaml
+patches:
+  - target:
+      kind: Deployment
+      name: my-app
+    patch: |-
+      - op: add
+        path: /spec/template/spec/containers/0/env/-
+        value:
+          name: LOG_LEVEL
+          value: "debug"
+      - op: replace
+        path: /spec/replicas
+        value: 5
+```
+
+## ConfigMap and Secret Generators
+
+```yaml
+configMapGenerator:
+  - name: app-config
+    literals:
+      - LOG_LEVEL=info
+      - DB_HOST=postgres.default.svc
+  - name: app-scripts
+    files:
+      - scripts/init.sh
+
+secretGenerator:
+  - name: db-credentials
+    literals:
+      - username=admin
+      - password=changeme
+    type: kubernetes.io/basic-auth
+```
+
+Generators append a content hash to the name automatically, enabling rolling updates on config changes.
+
+## Components
+
+Reusable cross-cutting features that can be included in any overlay:
+
+```yaml
+# components/monitoring/kustomization.yaml
+apiVersion: kustomize.config.k8s.io/v1alpha1
+kind: Component
+
+resources:
+  - servicemonitor.yaml
+
+patches:
+  - target:
+      kind: Deployment
+    patch: |-
+      - op: add
+        path: /spec/template/metadata/annotations/prometheus.io~1scrape
+        value: "true"
+```
+
+Include in an overlay:
+
+```yaml
+# overlays/production/kustomization.yaml
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+  - ../../base
+components:
+  - ../../components/monitoring
+```
+
+## Image Transformer
+
+```yaml
+images:
+  - name: my-app
+    newName: ghcr.io/org/my-app
+    newTag: "v1.4.2"
+  - name: sidecar
+    newName: ghcr.io/org/sidecar
+    digest: sha256:abcdef1234567890
+```
+
+Prefer `digest` over `newTag` in production for immutable references.
+
+## When to Use Kustomize vs Helm
+
+| Scenario | Kustomize | Helm |
+|---|---|---|
+| Environment-specific overlays on static manifests | Preferred | Overkill |
+| Complex parameterization with many knobs | Awkward | Preferred |
+| CRDs and operator-managed resources | Good fit | Good fit |
+| Third-party chart consumption | Cannot | Required |
+| Simple internal services with 2-3 envs | Preferred | Acceptable |
+| Shared library of templates | Not supported | Library charts |
+
+## Production Overlay Example
+
+```yaml
+# overlays/production/kustomization.yaml
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources:
+  - ../../base
+  - hpa.yaml
+
+namespace: production
+
+commonLabels:
+  environment: production
+
+patches:
+  - path: resource-patch.yaml
+
+configMapGenerator:
+  - name: app-config
+    behavior: merge
+    literals:
+      - LOG_LEVEL=warn
+      - ENABLE_DEBUG=false
+
+images:
+  - name: my-app
+    newName: ghcr.io/org/my-app
+    newTag: "v2.1.0"
+```
+
+## LLM Mistake Checklist
+
+1. **Used `bases:` instead of `resources:`** -- `bases` is deprecated; always use `resources` for base references.
+2. **Strategic merge patch missing `name` in metadata** -- Kustomize cannot match the patch to a resource without it.
+3. **commonLabels applied to resources with immutable selectors** -- breaks Deployments on update because `spec.selector.matchLabels` is immutable after creation.
+4. **Forgot content hash in Secret/ConfigMap references** -- hardcoded name in Deployment envFrom does not match generated name with hash suffix.
+5. **JSON patch with wrong array index** -- use `/-` to append, explicit index to target a known position.
+6. **Component declared with wrong apiVersion** -- components use `v1alpha1`, not `v1beta1`.
+7. **Relative path wrong in overlay** -- must point to the directory containing kustomization.yaml, not individual files.
+8. **Missing `behavior: merge` on generator overlay** -- creates a new ConfigMap instead of merging with the base one.