ada/agentguard-ci
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

readme edits

Browse Source
This commit is contained in:
ada
2026-04-20 18:07:49 -06:00
parent 6f0252776f
commit fefe72d177
1 changed files with 72 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+72 -37
View File
@@ -1,68 +1,103 @@
# agentguard-ci # 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: - Runs TruffleHog for secret scanning.
* **TruffleHog**: Verifies leaked API keys dynamically to prevent false-positives from AI hallucinations. - Runs Semgrep for first-party code scanning.
* **Semgrep**: Scans first-party application logic for vulnerabilities (e.g., SQLi, XSS). - Runs KICS for infrastructure misconfiguration scanning.
* **Socket.dev**: Analyzes dependencies for supply chain attacks, malware, and typosquatting. - Runs Socket.dev for dependency risk scanning.
* **Pulumi CrossGuard**: Validates Infrastructure as Code against policy packs. - Runs Syft and Grype for SBOM generation and vulnerability scanning.
* **Syft + Grype**: Generates SBOMs and scans for container vulnerabilities scored via EPSS. - Runs Pulumi CrossGuard for policy-pack validation.
* **KICS**: Scans infrastructure misconfigurations. - Uploads supported reports to DefectDojo when enabled.
* **DefectDojo & MinIO**: Uploads findings to a centralized ASPM dashboard and raw SARIF/JSON reports to S3-compatible storage. - Uploads raw reports to S3-compatible storage when enabled.
* **Policy Enforcement**: Custom TypeScript logic automatically fails the build if any findings exceed your defined CVSS severity threshold. - 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
* **Argo Workflows** - Infisical Kubernetes Operator, if you want this chart to sync secrets automatically
* **Infisical Kubernetes Operator** (for secret injection) - DefectDojo, if you want report ingestion enabled
* **DefectDojo** (for vulnerability dashboards) - MinIO or another S3-compatible store, if you want raw report uploads enabled
* **MinIO / S3** (for raw report storage)
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 ```bash
cd tools cd tools
docker build -t your-registry/agentguard-tools:latest . docker build -t your-registry/agentguard-tools:latest .
docker push 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 ### 2. Configure values
Update `helm/values.yaml` (if applicable) and configure your Infisical integration:
Start from [`helm/values.yaml`](helm/values.yaml) and set at least:
```yaml ```yaml
pipeline: pipeline:
enabled: true toolsImage:
repository: your-registry/agentguard-tools
tag: latest
infisical: infisical:
workspaceSlug: "your-workspace-id" enabled: true
projectSlug: "your-project-id" workspaceSlug: your-workspace-id
projectSlug: your-project-id
storage:
enabled: false
defectdojo:
enabled: false
``` ```
### 3. Deploy via Helm 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.
Install the pipeline and its associated resources to your cluster:
If you do not use Infisical, create the `amp-security-pipeline-secrets` secret yourself before running the workflow.
### 3. Deploy the chart
```bash ```bash
helm upgrade --install agentguard-ci ./helm -n argo 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. ## 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.