Skip to content

SecOps Workflow

This page describes the repository-level SecOps workflow for the homelab GitOps stack.

The controls are added one tool at a time. CI checks and audit-only workflows come before any live-cluster enforcement.

Current Scope

The repository already contains several security-relevant services:

  • DefectDojo for vulnerability tracking.
  • OpenVAS for vulnerability scanning.
  • Wazuh for runtime/security monitoring.
  • Renovate for dependency update pull requests.
  • SOPS age preparation for future encrypted secret files.
  • Infisical and Vaultwarden for secret-management workflows.
  • AWX and Semaphore for future remediation workflows.

The current repository also has known tracked secret-like files. New controls must not print secret values or require immediate history cleanup without a separate rotation and rollback plan.

Versioned Validation Container

Forgejo validation runs in the versioned image git.mutana.fr/kardudu/k8s-validation:v0.1.0. The image contains the pinned kubectl v1.36.2, Helm v3.19.4, Gitleaks v8.30.1, Kubeconform v0.8.0, Trivy v0.72.0, and the Python dependencies used by the Makefile validation targets.

The image source is ci/validation/. The .forgejo/workflows/build-validation-image.yaml workflow builds and publishes multi-architecture images to the Forgejo container registry. Bump VALIDATION_IMAGE_VERSION in both workflows when the Dockerfile, pinned tools, or Python validation dependencies change. The validation workflow does not depend on a cache hit for executable tools. Registry publishing and image pulls use the out-of-band Forgejo repository secret FORGEJO_PACKAGES_TOKEN; configure it with package read/write permission for kardudu/k8s-validation and never commit its value. The workflows retain DOCKER_BUILDER_TOKEN as a fallback for installations that grant job-token package access.

Local validation can continue to use host-installed tools or the existing .venv-docs environment. make deps remains the local bootstrap command; inside the validation image, the preinstalled tools are selected automatically.

Planned Control Chain

Git / CI
  -> secret scanning
  -> Kubernetes manifest scanning
  -> image vulnerability scanning
  -> vulnerability tracking
  -> Kubernetes policy in audit mode
  -> runtime detection
  -> AWX or Ansible remediation

Secret Scanning

The first control is Gitleaks secret scanning.

Initial behavior:

  • Forgejo CI runs pinned Gitleaks v8.30.1 from the versioned validation image.
  • Scan only the new commit range introduced by a pull request or push.
  • Redact findings in logs.
  • Avoid committing a baseline report.
  • Avoid scanning or printing known secret-like files outside the changed Git range.

Local usage:

make secops-secret-scan

Scan an explicit range:

make secops-secret-scan GITLEAKS_LOG_OPTS="origin/dev..HEAD"

The local command requires gitleaks on PATH. Forgejo CI provides the pinned binary through the validation image.

Kubernetes Manifest Scanning

The second control is Kubeconform schema validation for rendered standardized overlays.

Initial behavior:

  • Forgejo CI runs pinned Kubeconform v0.8.0 from the versioned validation image.
  • The scan renders each standardized overlays/<cluster>/ path with kubectl kustomize --enable-helm.
  • Missing schemas for custom resources are ignored so existing Traefik, Fleet, and workload CRDs do not block the first pass.
  • Built-in Kubernetes resources are validated in strict mode.

Local usage:

make secops-manifest-scan

The local command requires kubeconform on PATH. Forgejo CI provides the pinned binary through the validation image.

Trivy Reports

The third control is Trivy report-only filesystem vulnerability scanning.

Initial behavior:

  • Forgejo CI runs pinned Trivy v0.72.0 from the versioned validation image.
  • The scan uses make secops-trivy-scan.
  • Reports are generated as JSON, SARIF, and table output.
  • Findings do not fail CI because Trivy runs with --exit-code 0.
  • Trivy secret scanning is disabled; Gitleaks owns repository secret detection.
  • Trivy misconfiguration scanning is not enabled in this first pass because the initial repository test produced a built-in Rego evaluation error. Kubeconform remains the Kubernetes manifest/schema check.

Local usage:

make secops-trivy-scan

Write reports into the local working tree when testing artifact output:

make secops-trivy-scan TRIVY_REPORT_DIR=.secops-reports/trivy TRIVY_CACHE_DIR=.trivy-cache

.secops-reports/ and .trivy-cache/ are ignored by Git.

Ansible Boundary

This k8s repository does not contain the main Ansible project layout.

The Ansible content is a separate workspace repository at:

/home/kardudu/ansible

That repository has split docs, inventories, playbooks, roles, plugins, tests, and vault files. Ansible linting should be added there or through a deliberate cross-repo CI handoff, not by making the k8s Forgejo workflow scan a sibling repository path.

Tool Status

The source of truth for tool status is:

context/secops-tools-tracker.md

The implementation roadmap is:

context/secops-plan.md

DefectDojo Boundary

DefectDojo is now deployed on both homelab and the production-like local cluster, and the local deployment is the central findings intake. CI uploads are wired but non-blocking and informational only.

Current state:

  • Trivy and Gitleaks reports from the k8s repo CI are re-imported into DefectDojo via make defectdojo-import, called from the Forgejo workflow.
  • Kubeconform findings can be imported as Generic Findings Import by setting DD_IMPORT_KUBECONFORM=1 (off by default until the schema is reviewed).
  • Nessus exports are pushed from the homelab side by defectdojo/scripts/nessus_to_defectdojo.sh.
  • All imports use /api/v2/reimport-scan/ to avoid duplicate findings.
  • The DefectDojo API token and URL are provided as Forgejo secrets (DEFECTDOJO_API_URL, DEFECTDOJO_API_TOKEN); they are never committed.
  • The DefectDojo /api IngressRoute route bypasses Authelia so token-based automation is not interrupted by forward-auth.

Details, taxonomy, and troubleshooting: Findings Ingestion.

Remaining decisions:

  • Review the first CI ingestion run and confirm the product/engagement/test naming is what you want before relying on the history.
  • Decide whether to enable DD_IMPORT_KUBECONFORM=1 permanently.
  • Decide whether CI uploads should stay non-blocking or become gating once the taxonomy is stable.

Do not add DefectDojo API tokens to Git.

Kubernetes Policy Boundary

Policy work must start in audit mode.

Do not deploy enforce-mode policies until:

  • Current workloads have been scanned.
  • Exceptions are documented.
  • Operators have reviewed audit results.
  • Rollback is clear.