@caoscompanybr/merlin 3.5.0

package/.merlin-core/skills/general/container-security/SKILL.md

@@ -0,0 +1,462 @@
+---
+name: container-security
+description: Container hardening (Dockerfile + base images) + Grype vulnerability scanning. Grype primary; Trivy noted as alternative pending its March 2026 supply chain incident review. Includes Dockerfile checklist, CI integration template, and triage matrix for findings.
+license: Apache-2.0
+metadata:
+  author: merlin-framework
+  version: "3.0.0"
+  auto_activate:
+    [
+      container-security,
+      container-scan,
+      grype,
+      image-vulnerability,
+      docker-hardening,
+      dockerfile-lint,
+    ]
+  tool_reminders:
+    [
+      Always pin base images by SHA digest not just tag — tags are mutable,
+      Run as non-root user (USER directive) — never run containerized apps as root,
+      Multi-stage builds keep final image minimal — only runtime deps in last stage,
+      Grype is the primary scanner choice (free Apache 2.0); Trivy alternative under review pending March 2026 supply chain incident,
+      HEALTHCHECK start-period must be tuned to actual app boot time — too short flags healthy as unhealthy,
+    ]
+---
+
+# Container Security Skill
+
+**Mission:** Every Dockerfile in a Merlin project meets a hardening baseline,
+and every container image is scanned for vulnerabilities before deploy. Use
+Grype as the primary scanner.
+
+This skill exists because a past project audit showed an unpinned
+base image (`FROM python:3.11-slim` without SHA digest), no image scanning in
+CI, and a HEALTHCHECK with `start-period=5s` despite the app needing ~90s to
+boot (causing transient unhealthy status during normal deploys).
+
+---
+
+## Why Grype (and not Trivy as primary)
+
+| Aspect            | Grype                                                                      | Trivy                                                                                                            |
+| ----------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| License           | Apache 2.0 (free)                                                          | Apache 2.0 (free)                                                                                                |
+| Maintainer        | Anchore                                                                    | Aqua Security                                                                                                    |
+| Vuln DB sources   | NVD + GHSA + Alpine + Debian + RHEL + Ubuntu + Amazon Linux + Oracle Linux | Aqua trivy-db (proprietary aggregation)                                                                          |
+| Risk scoring      | CVSS + EPSS + CISA KEV → composite risk score 0-10                         | CVSS severity only                                                                                               |
+| Scope             | Container images + filesystems + SBOM                                      | Containers + IaC + secrets + licenses + K8s (broader)                                                            |
+| GitHub stars      | 11.5k                                                                      | 31.7k                                                                                                            |
+| March 2026 status | Stable, no incidents                                                       | **Supply chain attack — release infra compromised, malicious images pushed to Docker Hub, DB updates suspended** |
+
+**Decision rationale:** Trivy is broader (Swiss Army knife) but its March 2026
+incident is unresolved — release infrastructure was compromised, attackers
+hijacked GitHub Actions tags, pushed malicious images, and DB updates remain
+suspended. Until upstream issues a clean post-mortem and resumes DB updates
+with audited infra, Grype is the safer default.
+
+**When to add Trivy back:** When (a) Aqua publishes a verified post-mortem
+detailing remediation, (b) DB updates resume with new release-signing
+process, (c) we want IaC + secrets + license scanning beyond Grype's vuln
+focus. Until then, use Grype for vuln scanning + gitleaks for secrets +
+hadolint for Dockerfile lint.
+
+---
+
+## When this skill activates
+
+- A new `Dockerfile` is being written or modified
+- A container is about to be built and pushed
+- Setting up CI for a project that uses Docker
+- After a CVE alert mentions a base image we use
+- During `engineering-audit` of a project with containers
+
+---
+
+## Part A — Dockerfile hardening checklist
+
+Apply to every Dockerfile in Merlin projects. Each item has a rationale.
+
+### A1. Pin base image by SHA digest (not just tag)
+
+```dockerfile
+# ❌ WRONG — tag is mutable, image content can change silently
+FROM python:3.11-slim
+
+# ✅ CORRECT — digest is immutable
+FROM python:3.11-slim@sha256:9c5f5b...full-64-char-sha
+```
+
+**Get the digest:**
+
+```bash
+docker pull python:3.11-slim
+docker inspect python:3.11-slim --format='{{index .RepoDigests 0}}'
+# Output: python:3.11-slim@sha256:9c5f...
+```
+
+**Update cadence:** Refresh digests monthly (security patches) or when CVE
+alerts affect the base. Use Renovate or Dependabot to automate this.
+
+### A2. Use minimal base images
+
+| Base                              | Size       | When to use                                                                             |
+| --------------------------------- | ---------- | --------------------------------------------------------------------------------------- |
+| `scratch`                         | 0 MB       | Static binaries (Go, Rust)                                                              |
+| `alpine`                          | ~7 MB      | Most apps; smaller attack surface but musl libc compatibility issues with some packages |
+| `*-slim` (debian-slim)            | ~80 MB     | Better compatibility than alpine; 4× larger                                             |
+| `*-distroless` (Google)           | ~20 MB     | Production runtimes; no shell, no package manager (huge security win)                   |
+| Full distros (`ubuntu`, `debian`) | 200-800 MB | ❌ Avoid for production — bloated, large attack surface                                 |
+
+For Merlin projects: prefer `-slim` for Python (compatibility), `-distroless`
+for Node.js production (post-build), `alpine` for Go/Rust where compatible.
+
+### A3. Run as non-root user
+
+```dockerfile
+# Create a dedicated user and use it for the runtime
+RUN groupadd --system --gid 1000 appuser && \
+    useradd --system --uid 1000 --gid appuser --shell /bin/bash --create-home appuser
+
+USER appuser
+WORKDIR /home/appuser
+```
+
+**Why:** If the container is compromised (RCE in app code), the attacker is
+limited to non-root inside the container — can't write to `/etc`, can't
+install packages, can't escape via privileged operations.
+
+### A4. Multi-stage builds
+
+```dockerfile
+# ----- Build stage -----
+FROM python:3.11-slim@sha256:... AS builder
+WORKDIR /build
+COPY requirements.txt .
+RUN pip install --user --no-cache-dir -r requirements.txt
+COPY src/ ./src/
+
+# ----- Runtime stage -----
+FROM python:3.11-slim@sha256:... AS runtime
+RUN useradd --system --uid 1000 appuser
+USER appuser
+WORKDIR /home/appuser
+COPY --from=builder --chown=appuser:appuser /root/.local /home/appuser/.local
+COPY --from=builder --chown=appuser:appuser /build/src ./src
+ENV PATH=/home/appuser/.local/bin:$PATH
+HEALTHCHECK --interval=30s --timeout=10s --start-period=120s \
+  CMD curl -fsS http://localhost:8000/health || exit 1
+CMD ["python", "-m", "src.main"]
+```
+
+**Why:** Build tools (compilers, dev headers, package managers) stay in the
+builder stage. The runtime image only contains what's needed to RUN the app
+— smaller, fewer CVEs, less attack surface.
+
+### A5. HEALTHCHECK with realistic `--start-period`
+
+```dockerfile
+# ❌ WRONG — a real-world mistake (5s for a ~90s boot)
+HEALTHCHECK --start-period=5s ...
+
+# ✅ CORRECT — measure actual boot time + 50% buffer
+HEALTHCHECK --interval=30s --timeout=10s --start-period=120s ...
+```
+
+**How to tune:** Time a cold start: `time docker run --rm <image> /bin/true`
+
+- application warm-up. Set `--start-period` to that + 30%. For example, an agent
+  service that needs ~90s to warm up (framework init + model load + DB + cache
+  connections) → use 120s.
+
+### A6. Don't expose secrets via ENV in image
+
+```dockerfile
+# ❌ WRONG — secrets baked into image layers (visible to anyone with image access)
+ENV DATABASE_PASSWORD=hunter2
+
+# ✅ CORRECT — secrets injected at runtime via -e or secret manager
+# (Dockerfile has no secret. Runtime: docker run -e DATABASE_PASSWORD=... or use Docker secrets)
+```
+
+Image layers are public to anyone who can `docker pull`. Even `RUN
+--mount=type=secret` is preferable to ENV for build-time secrets.
+
+### A7. `.dockerignore` covers `.env*`, `.git`, `node_modules`, secrets
+
+```
+# .dockerignore — mirrors .gitignore patterns + build artifacts
+.env*
+.git
+.github
+node_modules
+__pycache__
+*.pyc
+.pytest_cache
+.venv
+.idea
+.vscode
+*.log
+*.pem
+*.key
+.merlin-core
+.merlin
+```
+
+**Why:** Without `.dockerignore`, `COPY . .` ships your entire dev environment
+including secrets, IDE configs, git history, and dependency caches into the
+image.
+
+### A8. Drop unnecessary capabilities
+
+In `docker-compose.yml` or `docker run`:
+
+```yaml
+services:
+  app:
+    cap_drop: [ALL]
+    cap_add: [NET_BIND_SERVICE] # only if you need port <1024
+    security_opt:
+      - no-new-privileges:true
+    read_only: true # if app doesn't write to FS at runtime
+    tmpfs:
+      - /tmp # if app needs writable /tmp
+```
+
+### A9. Lint the Dockerfile
+
+```bash
+# hadolint catches common Dockerfile mistakes
+docker run --rm -i hadolint/hadolint < Dockerfile
+```
+
+Add to CI (see Part C).
+
+---
+
+## Part B — Grype scanning workflow
+
+### B1. Local scan (before push)
+
+```bash
+# Install Grype
+curl -sSfL https://raw.githubusercontent.com/anchore/grype/main/install.sh | sh -s -- -b /usr/local/bin
+
+# Scan a built image
+grype <image-name>:<tag>
+
+# Scan with risk score (CVSS + EPSS + CISA KEV)
+grype <image>:<tag> --add-cpes-if-none -o table
+
+# Scan and fail on findings >= severity
+grype <image>:<tag> --fail-on high
+
+# Scan a Dockerfile (without building — uses image references)
+grype dir:.
+```
+
+### B2. CI scan template
+
+```yaml
+# .github/workflows/container-scan.yml
+name: Container Vulnerability Scan (Grype)
+
+on:
+  push:
+    branches: [main, develop]
+    paths: ["**/Dockerfile", "**/docker-compose*.yml"]
+  pull_request:
+    branches: [main]
+    paths: ["**/Dockerfile", "**/docker-compose*.yml"]
+  schedule:
+    - cron: "0 6 * * 1" # Weekly Monday 06:00 UTC — catches new CVEs in old images
+  workflow_dispatch:
+
+jobs:
+  grype-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build image (for scanning)
+        run: docker build -t scan-target:latest -f path/to/Dockerfile .
+
+      - name: Run Grype
+        uses: anchore/scan-action@v4
+        with:
+          image: scan-target:latest
+          severity-cutoff: high # Fail build on high or critical
+          fail-build: true
+          output-format: sarif
+
+      - name: Upload SARIF to GitHub Security tab
+        if: always()
+        uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: ${{ steps.scan.outputs.sarif }}
+
+  hadolint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: hadolint/hadolint-action@v3.1.0
+        with:
+          dockerfile: path/to/Dockerfile
+          failure-threshold: warning
+```
+
+### B3. Triage matrix for findings
+
+When Grype reports CVEs, decide action by composite risk:
+
+| Severity | EPSS (exploit prob) | KEV (known exploited) | Action                                                 |
+| -------- | ------------------- | --------------------- | ------------------------------------------------------ |
+| Critical | >0.5                | Yes                   | 🔴 **BLOCK DEPLOY** — patch immediately, no exceptions |
+| Critical | <0.5                | No                    | 🟠 Patch within 7 days                                 |
+| High     | >0.5                | Any                   | 🟠 Patch within 14 days                                |
+| High     | <0.5                | No                    | 🟡 Patch within 30 days                                |
+| Medium   | Any                 | No                    | 🟢 Patch in next sprint                                |
+| Low      | Any                 | No                    | ⚪ Track but defer                                     |
+
+**EPSS** = Exploit Prediction Scoring System (probability someone will
+exploit in next 30 days). **KEV** = CISA Known Exploited Vulnerabilities
+catalog. Both are surfaced by Grype's risk score.
+
+### B4. Suppression / accepted-risk pattern
+
+When a finding is unfixable upstream OR doesn't apply to our usage:
+
+```yaml
+# .grype.yaml — project root
+ignore:
+  - vulnerability: CVE-2024-12345
+    reason: "Not applicable — feature X is disabled in our config"
+    expires: "2026-12-31" # Force re-evaluation periodically
+    approver: <your-name>
+    date: <YYYY-MM-DD>
+```
+
+Same convention as `.gitleaks.toml`: every entry must be documented.
+
+---
+
+## Part C — Composite CI workflow
+
+Combine Grype + hadolint + the gitleaks workflow from `secret-safe-commit`:
+
+```yaml
+# .github/workflows/security.yml
+name: Security Pipeline
+
+on: [push, pull_request]
+
+jobs:
+  secrets:
+    uses: ./.github/workflows/secret-scan.yml # From secret-safe-commit skill
+
+  dockerfile-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: hadolint/hadolint-action@v3.1.0
+        with:
+          dockerfile: path/to/Dockerfile
+
+  vuln-scan:
+    runs-on: ubuntu-latest
+    needs: [dockerfile-lint]
+    steps:
+      - uses: actions/checkout@v4
+      - run: docker build -t scan-target -f path/to/Dockerfile .
+      - uses: anchore/scan-action@v4
+        with:
+          image: scan-target
+          severity-cutoff: high
+          fail-build: true
+```
+
+---
+
+## Common gotchas
+
+### Gotcha #1 — Grype DB needs internet on first run
+
+`grype` downloads its vuln DB on first invocation (~50MB). In air-gapped
+environments, pre-fetch with `grype db update` and cache.
+
+### Gotcha #2 — SHA digest changes when image is rebuilt upstream
+
+When `python:3.11-slim` gets a security update, the tag points to a NEW
+digest. Your pinned digest still works (immutable) but doesn't get the
+patch. Use Renovate or a monthly bump cadence.
+
+### Gotcha #3 — Multi-arch images have one digest per platform
+
+`python:3.11-slim@sha256:abc...` may pull different content on `linux/amd64`
+vs `linux/arm64`. Pin per-platform if you build multi-arch.
+
+### Gotcha #4 — `USER appuser` doesn't work if appuser doesn't exist yet
+
+```dockerfile
+# ❌ WRONG — order matters
+USER appuser
+RUN useradd appuser  # too late, USER directive already applied
+
+# ✅ CORRECT
+RUN useradd appuser
+USER appuser
+```
+
+### Gotcha #5 — HEALTHCHECK doesn't work in Kubernetes (use livenessProbe)
+
+If you deploy to k8s, HEALTHCHECK in Dockerfile is ignored. Define
+`livenessProbe` and `readinessProbe` in your manifest.
+
+### Gotcha #6 — `read_only: true` breaks apps that write logs
+
+Most apps write to stdout/stderr (collected by Docker), but some libraries
+write to files. If `read_only: true` breaks the app, add tmpfs mounts for
+the specific writable paths instead of dropping read-only entirely.
+
+---
+
+## Worked example — applying this to an existing Dockerfile
+
+Current state (`path/to/Dockerfile`):
+
+- ❌ `FROM python:3.11-slim` (no SHA pinning)
+- ✅ `USER appuser` (non-root)
+- ❌ `HEALTHCHECK --start-period=5s` (way too short for ~90s boot)
+- ❌ Single-stage build (build tools shipped in runtime)
+- ❌ No `.dockerignore` verified
+- ❌ No CI scanning
+
+**Recommended actions** (prioritized):
+
+1. **Now:** Bump `start-period=120s` (fixes false-unhealthy status)
+2. **This week:** Pin base image by SHA digest
+3. **This week:** Add `.dockerignore` covering `.env*`, `.git`, `__pycache__`
+4. **This month:** Convert to multi-stage build
+5. **This month:** Add Grype + hadolint CI workflow
+6. **This month:** Use distroless for runtime stage if compatible with the app's runtime dependencies
+
+---
+
+## Related skills
+
+- **`secret-safe-commit`** — composes the secrets scanning side of the security CI
+- **`vps-security-hardening`** — the host-level twin of container hardening
+- **`engineering-audit`** — security axis includes Dockerfile review
+- **`ci-security-baseline`** (Tier 2 roadmap) — pulls all security workflows together
+- **`dependency-audit`** (Tier 2 roadmap) — npm audit + pip-audit for app deps (vs base image)
+
+---
+
+## References
+
+- [Grype docs](https://github.com/anchore/grype)
+- [hadolint Dockerfile linter](https://github.com/hadolint/hadolint)
+- [Distroless images (Google)](https://github.com/GoogleContainerTools/distroless)
+- [Trivy March 2026 incident analysis](https://github.com/aquasecurity/trivy/issues) — track resolution before re-adopting
+- [CISA Known Exploited Vulnerabilities catalog](https://www.cisa.gov/known-exploited-vulnerabilities-catalog)
+- [EPSS (Exploit Prediction Scoring System)](https://www.first.org/epss/)

package/.merlin-core/skills/general/context-management/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: context-management
+description: Context lifecycle management for Merlin agents. Teaches agents to monitor context usage, create handoffs proactively, and validate fresh context on phase transitions.
+license: Apache-2.0
+metadata:
+  author: merlin-framework
+  version: "3.0.0"
+  auto_activate:
+    [context-handoff, session-reset, context-depleted, phase-transition]
+---
+
+# Context Management
+
+## Context Brackets
+
+Merlin's Alkimia engine tracks context consumption in four brackets:
+
+| Bracket  | Remaining | Action                                                             |
+| -------- | --------- | ------------------------------------------------------------------ |
+| FRESH    | 60-100%   | Normal operation. All layers active.                               |
+| MODERATE | 40-60%    | Be mindful of scope. Avoid loading large files unnecessarily.      |
+| DEPLETED | 25-40%    | Create handoff soon. Summarize progress. Finish current task only. |
+| CRITICAL | 0-25%     | STOP new work immediately. Create handoff NOW. Save all decisions. |
+
+## Context Warnings
+
+When you receive `[CONTEXT MODERATE]`, `[CONTEXT DEPLETED]`, or `[CONTEXT CRITICAL]` warnings:
+
+1. Acknowledge the warning internally
+2. Adjust your scope based on the bracket level
+3. At DEPLETED: finish current task, then run `/handoff`
+4. At CRITICAL: stop immediately and run `/handoff`
+
+## Phase Transition Protocol (Folloni Funnel)
+
+When transitioning between Folloni phases (Research -> Architecture -> Implementation):
+
+1. **BEFORE ending current phase:** Run `/handoff` to save context
+2. The handoff MUST include:
+   - What was accomplished
+   - Key decisions made (with rationale)
+   - Rejected alternatives
+   - Next steps for the new phase
+   - Key files to read
+3. **Start a NEW Claude Code session** for the next phase
+4. **In the new session:** Run `/resume-handoff` with the handoff path
+5. Load ONLY the output document from the previous phase
+6. Do NOT attempt to recall information from the previous session
+
+## Handoff Triggers
+
+Create a handoff when ANY of these conditions are met:
+
+- Context bracket reaches DEPLETED (you'll get a `[CONTEXT DEPLETED]` warning)
+- Phase transition is needed in the Folloni Funnel
+- You receive an `[AUTO-SUMMARIZATION]` trigger
+- The user explicitly asks for a handoff
+
+## Resume Protocol
+
+When resuming from a handoff:
+
+1. Read the handoff document fully before doing anything
+2. Check that the git branch matches what the handoff expects
+3. Read all key files mentioned in the handoff
+4. Create a todo list from the remaining work
+5. Do NOT re-do work that is marked as completed
+
+## Memory Hints
+
+At DEPLETED and CRITICAL brackets, the Alkimia engine automatically retrieves relevant memories from `thoughts/shared/` (plans, research, handoffs, decisions). These appear as `[MEMORY HINTS]` in your context. Use them to maintain awareness of project history.
+
+## Best Practices
+
+- Prefer reading specific file sections over entire large files
+- Use Grep/Glob for targeted searches instead of reading directories
+- When building large features, break work into smaller phases with handoffs
+- Always check git status before starting work (avoids duplicate effort)
+- If a conversation feels long, proactively suggest a handoff