From fefe72d177dd75222e81f4f24a21e8b2887a85cb Mon Sep 17 00:00:00 2001 From: ada Date: Mon, 20 Apr 2026 18:07:49 -0600 Subject: [PATCH] readme edits --- README.md | 109 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 72 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index 4b8479c..6379f96 100644 --- a/README.md +++ b/README.md @@ -1,68 +1,103 @@ # agentguard-ci -A DevSecOps Argo Workflows pipeline specifically designed to protect against AI coding agent hallucinations, supply chain attacks, and security misconfigurations in a homelab or solo-developer environment. +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. -## 📖 The Problem +## Problem -AI coding agents are highly productive "junior developers," but they lack intrinsic context. They frequently hallucinate dummy credentials, introduce insecure application logic, or pull in new, potentially typosquatted dependencies. +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 pipeline acts as a strict, automated gatekeeper that prioritizes zero-noise alerting, allowing you to maintain high development velocity without compromising the security of your exposed homelab. +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. -## 🏗️ Architecture & Features +## What the pipeline does -This project deploys an **Argo ClusterWorkflowTemplate** that orchestrates a parallel security scanning matrix whenever code is pushed: -* **TruffleHog**: Verifies leaked API keys dynamically to prevent false-positives from AI hallucinations. -* **Semgrep**: Scans first-party application logic for vulnerabilities (e.g., SQLi, XSS). -* **Socket.dev**: Analyzes dependencies for supply chain attacks, malware, and typosquatting. -* **Pulumi CrossGuard**: Validates Infrastructure as Code against policy packs. -* **Syft + Grype**: Generates SBOMs and scans for container vulnerabilities scored via EPSS. -* **KICS**: Scans infrastructure misconfigurations. -* **DefectDojo & MinIO**: Uploads findings to a centralized ASPM dashboard and raw SARIF/JSON reports to S3-compatible storage. -* **Policy Enforcement**: Custom TypeScript logic automatically fails the build if any findings exceed your defined CVSS severity threshold. +- 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. -For deep-dive architecture decisions, see the [Pipeline Overview ADR](docs/pipeline-overview.md) and [Secret Strategy ADR](docs/secret-strategy.md). +## Prerequisites -## 🚀 Prerequisites +Install these separately in your cluster before using this chart: -Before installing the pipeline, ensure your Kubernetes cluster has the following installed: -* **Argo Workflows** -* **Infisical Kubernetes Operator** (for secret injection) -* **DefectDojo** (for vulnerability dashboards) -* **MinIO / S3** (for raw report storage) +- 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 API keys or tokens for: Socket.dev, Pulumi, AWS/MinIO, and DefectDojo. +You will also need the corresponding credentials for Socket.dev, Pulumi, AWS or MinIO, and DefectDojo. -## 🛠️ Installation +## Validation workflow + +For fast validation while wiring up infrastructure, use these tools together: + +- `helm lint ./helm` +- `helm template agentguard-ci ./helm` +- `helm template agentguard-ci ./helm | kubectl apply --dry-run=client -f -` +- `helm template agentguard-ci ./helm | kubectl apply --dry-run=server -f -` +- `argo lint rendered.yaml` + +Notes: + +- `helm lint` catches Helm chart problems. +- `kubectl --dry-run=client` catches basic Kubernetes schema issues without talking to the cluster. +- `kubectl --dry-run=server` is better once the cluster already has the Argo and Infisical CRDs installed. +- `argo lint` is the most useful Argo-specific check once you have the Argo CLI installed. + +## Installation + +### 1. Build the tools image + +The workflow uses custom TypeScript utilities for policy enforcement and DefectDojo uploads. -### 1. Build the Pipeline Tools Image -The pipeline relies on custom TypeScript logic (e.g., CVSS enforcement and API uploads). Build and push this image to your registry: ```bash cd tools docker build -t your-registry/agentguard-tools:latest . docker push your-registry/agentguard-tools:latest ``` -*(Make sure to update `clusterworkflowtemplate.yaml` with your custom image if you do not use `agentguard-tools:latest`)* -### 2. Configure Helm Values -Update `helm/values.yaml` (if applicable) and configure your Infisical integration: +### 2. Configure values + +Start from [`helm/values.yaml`](helm/values.yaml) and set at least: + ```yaml pipeline: - enabled: true + toolsImage: + repository: your-registry/agentguard-tools + tag: latest + infisical: - workspaceSlug: "your-workspace-id" - projectSlug: "your-project-id" + enabled: true + workspaceSlug: your-workspace-id + projectSlug: your-project-id + +storage: + enabled: false + +defectdojo: + enabled: false ``` -### 3. Deploy via Helm -Install the pipeline and its associated resources to your cluster: +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. + +### 3. Deploy the chart + ```bash helm upgrade --install agentguard-ci ./helm -n argo ``` -## 🔐 Secret Management Integration +## DefectDojo integration -To prevent hardcoded secrets in the pipeline, this project uses the **Infisical Kubernetes Operator**. +DefectDojo is not installed by this repository. -When you deploy the Helm chart, it creates an `InfisicalSecret` Custom Resource (`helm/templates/infisical-secret.yaml`). The Infisical Operator securely fetches your vault secrets (like `SOCKET_DEV_API_KEY` and `DEFECTDOJO_API_TOKEN`) and synchronizes them into a standard Kubernetes `Secret` named `amp-security-pipeline-secrets`. +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`](tools/src/upload-defectdojo.ts). -The Argo Workflow then mounts this standard secret as environment variables inside the scanning containers, ensuring zero secret leakage in the Git repository. \ No newline at end of file +## 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.