other changes

2026-04-20 01:25:44 -06:00
parent 38ff2f4fde
commit 1036fce55e
11 changed files with 2035 additions and 171 deletions
@@ -1,3 +1,68 @@
 # agentguard-ci

-A DevSecOps Argo Workflows pipeline to protect against AI coding agent hallucinations and supply chain attacks.
+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.
+
+## 📖 The 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. 
+
+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.
+
+## 🏗️ Architecture & Features
+
+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.
+
+For deep-dive architecture decisions, see the [Pipeline Overview ADR](docs/pipeline-overview.md) and [Secret Strategy ADR](docs/secret-strategy.md).
+
+## 🚀 Prerequisites
+
+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)
+
+You will also need API keys or tokens for: Socket.dev, Pulumi, AWS/MinIO, and DefectDojo.
+
+## 🛠️ Installation
+
+### 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:
+```yaml
+pipeline:
+  enabled: true
+infisical:
+  workspaceSlug: "your-workspace-id"
+  projectSlug: "your-project-id"
+```
+
+### 3. Deploy via Helm
+Install the pipeline and its associated resources to your cluster:
+```bash
+helm upgrade --install agentguard-ci ./helm -n argo
+```
+
+## 🔐 Secret Management Integration
+
+To prevent hardcoded secrets in the pipeline, this project uses the **Infisical Kubernetes Operator**.
+
+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`. 
+
+The Argo Workflow then mounts this standard secret as environment variables inside the scanning containers, ensuring zero secret leakage in the Git repository.