agentguard-ci/README.md

agentguard-ci

A DevSecOps Argo Workflows pipeline designed to protect against AI coding agent hallucinations, supply chain attacks, and security misconfigurations in a homelab or solo-developer environment.

Problem

AI coding agents are highly productive junior developers, but they lack intrinsic context. They can hallucinate credentials, introduce insecure logic, or pull in risky dependencies.

This project adds a reusable security gate in front of deployment by cloning a repository into an Argo workflow, running multiple scanners in parallel, uploading supported results to DefectDojo and object storage, and enforcing a CVSS-based policy threshold.

What the pipeline does

• Runs TruffleHog for secret scanning.
• Runs Semgrep for first-party code scanning.
• Runs KICS for infrastructure misconfiguration scanning.
• Runs Socket.dev for dependency risk scanning.
• Runs Syft and Grype for SBOM generation and vulnerability scanning.
• Runs Pulumi CrossGuard for policy-pack validation.
• Uploads supported reports to DefectDojo when enabled.
• Uploads raw reports to S3-compatible storage when enabled.
• Fails the workflow when findings meet or exceed the configured CVSS threshold.

Prerequisites

Install these separately in your cluster before using this chart:

• Argo Workflows
• Infisical Kubernetes Operator, if you want this chart to sync secrets automatically
• DefectDojo, if you want report ingestion enabled
• MinIO or another S3-compatible store, if you want raw report uploads enabled

You will also need the corresponding credentials for Socket.dev, Pulumi, S3-compatible object storage, and DefectDojo.

Reading the chart

If the Helm templates start to feel too abstract, use these two files together:

• helm/values.schema.json documents the expected shape and meaning of the values file.
• docs/rendered/default-clusterworkflowtemplate.yaml shows the default rendered ClusterWorkflowTemplate without Helm directives in the way.

The rendered reference reflects the default values in helm/values.yaml, so optional storage, DefectDojo, and Infisical resources are intentionally omitted there.

Validation workflow

For fast validation while wiring up infrastructure, use these tools together:

• ./scripts/check-chart.sh
• RUN_KUBECTL_CLIENT_CHECK=1 ./scripts/check-chart.sh
• RUN_KUBECTL_SERVER_CHECK=1 ./scripts/check-chart.sh

What each mode does:

• ./scripts/check-chart.sh runs the fast offline checks used by the repo-managed pre-commit hook: helm lint, helm template, and argo lint --offline.
• RUN_KUBECTL_CLIENT_CHECK=1 ./scripts/check-chart.sh adds a client-side kubectl dry-run. This is optional because CRD-heavy manifests can still be environment-sensitive here.
• RUN_KUBECTL_SERVER_CHECK=1 ./scripts/check-chart.sh adds a server-side dry-run against your current cluster context, which is the strongest validation once the Argo and Infisical CRDs are installed.

Install the shared git hook once per clone:

git config core.hooksPath .githooks

Notes:

• helm lint catches Helm chart problems.
• helm template proves the chart renders successfully with the current values.
• argo lint --offline is the most useful Argo-specific local check because it validates the rendered ClusterWorkflowTemplate without needing cluster access.
• kubectl --dry-run=client is weaker for CRDs than Argo lint, so it is included as an optional extra check instead of the default hook behavior.
• kubectl --dry-run=server is best once the cluster already has the Argo and Infisical CRDs installed.
• CI should still rerun the same baseline checks even if pre-commit already passed, because hooks are local and bypassable. The usual CI extra is the server-side kubectl dry-run once a cluster with the needed CRDs is available.

Installation

1. Build the tools image

The workflow uses custom TypeScript utilities for policy enforcement and DefectDojo uploads.

cd tools
docker build -t your-registry/agentguard-tools:latest .
docker push your-registry/agentguard-tools:latest

2. Configure values

Start from helm/values.yaml and set at least:

pipeline:
  toolsImage:
    repository: your-registry/agentguard-tools
    tag: latest

infisical:
  enabled: true
  workspaceSlug: your-workspace-id
  projectSlug: your-project-id

storage:
  enabled: false

defectdojo:
  enabled: false

Keep storage.enabled and defectdojo.enabled disabled until those services are actually installed and reachable. Keep infisical.enabled disabled until the operator is installed and your project identifiers are ready.

If you do not use Infisical, create the amp-security-pipeline-secrets secret yourself before running the workflow. For storage uploads, the secret should contain S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY.

3. Deploy the chart

helm upgrade --install agentguard-ci ./helm -n argo

DefectDojo integration

DefectDojo is not installed by this repository.

You install DefectDojo separately, then enable this chart's upload step. When enabled, the workflow uploads supported reports into DefectDojo through the API using the custom uploader in tools/src/upload-defectdojo.ts.

Secret management

When infisical.enabled is true, this chart creates an InfisicalSecret that syncs the runtime credentials needed by the workflow into the amp-security-pipeline-secrets Kubernetes secret.