From 43d6ad6d6cefb610ba78577eb8abb62e27418003 Mon Sep 17 00:00:00 2001 From: Elizabeth W Date: Fri, 15 May 2026 23:02:05 -0600 Subject: [PATCH] docs refining security scope --- README.md | 6 ++ docs/security-scope.md | 207 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 213 insertions(+) create mode 100644 docs/security-scope.md diff --git a/README.md b/README.md index 19a1b4c..8f72bea 100644 --- a/README.md +++ b/README.md @@ -113,6 +113,12 @@ If you do not use Infisical, create the `amp-security-pipeline-secrets` secret y helm upgrade --install agentguard-ci ./helm -n argo ``` +## Scope and boundaries + +This repository is intentionally focused on **source, IaC, and dependency scanning** before deployment. + +It does **not** try to be the full build-signing, deploy-admission, or runtime-security stack. For the explicit boundary, missing controls, and recommended sibling pipeline responsibilities, read [`docs/security-scope.md`](docs/security-scope.md). + ## DefectDojo integration DefectDojo is not installed by this repository. diff --git a/docs/security-scope.md b/docs/security-scope.md new file mode 100644 index 0000000..66d33d7 --- /dev/null +++ b/docs/security-scope.md @@ -0,0 +1,207 @@ +# Security Scope and Boundaries + +This repository is intentionally a **source, IaC, and dependency scanning pipeline**. +It is not a complete software supply chain or runtime security platform. + +The goal of this document is to make the scope explicit so users understand: + +- what this repository is designed to secure +- what it does not secure +- what additional controls are still required for a production or homelab deployment pipeline +- what requirements a sibling pipeline should meet if you want to fill the gaps + +## What this repository covers + +This repository provides a reusable pre-deploy security gate that scans a repository before deployment proceeds. + +Today it covers: + +- **Secret scanning** with TruffleHog in the pipeline and Gitleaks in local development guidance. +- **First-party code scanning** with Semgrep. +- **Infrastructure-as-code scanning** with KICS. +- **Dependency risk scanning** with Socket.dev. +- **SBOM generation and vulnerability scanning** with Syft and Grype. +- **Policy-pack validation** with Pulumi CrossGuard. +- **Finding export and triage plumbing** through optional DefectDojo and object storage uploads. +- **Dependency update automation support** through the Renovate preset and Renovate bot chart in this repository. + +In practical terms, this repository is strongest at: + +- stopping known-bad or suspicious changes before deploy +- reducing the chance that AI-generated insecure code or dependencies reach production +- creating visibility into code, IaC, dependency, and package vulnerability risk + +## What this repository does not cover + +This repository does **not** attempt to be responsible for every security control in a modern delivery system. + +It does not provide: + +- **Artifact signing** for container images, packages, or release bundles. +- **Build provenance / attestations** proving which trusted builder produced an artifact from which source revision. +- **Admission control verification** that only signed or attested artifacts may deploy. +- **Runtime threat detection** inside the cluster or host. +- **Network segmentation or runtime isolation** for the deployed applications. +- **DAST** or other black-box testing against a live running application. +- **Repository hosting configuration enforcement** such as branch protection, required reviews, CODEOWNERS, or token restrictions. +- **Application deployment hardening enforcement** such as checking whether deployed workloads run as non-root, drop capabilities, use read-only root filesystems, or have network policies. +- **Secure secret delivery for the scanned application** beyond the pipeline's own runtime secret needs. +- **Incident response, rollback, backup, disaster recovery, or patch SLAs**. + +Those areas still matter. They are simply outside the intended scope of this repository. + +## Why the scope stops here + +The security boundary for this repository is: + +1. clone a source repository +2. scan source, IaC, dependencies, and generated SBOM data +3. publish findings +4. fail or pass based on policy + +That boundary is useful because it keeps this repository focused, fast, and reusable. +If artifact build security, deploy admission, and runtime controls are mixed directly into this pipeline, the repository stops being a clear pre-deploy scanner and turns into a broader platform. + +This repository should remain the **shift-left scanning gate**, not the entire delivery architecture. + +## What a complete deployment pipeline still needs + +If you are deploying software after this pipeline passes, you still need additional controls elsewhere. + +At a minimum, a production-grade or public homelab deployment flow should also have: + +### 1. Repository and change-management controls + +These controls protect the trustworthiness of the source before scanning even begins. + +Recommended controls: + +- branch protection on default and release branches +- required pull request reviews for sensitive paths +- `CODEOWNERS` for pipeline, deployment, and policy files +- restricted direct pushes to protected branches +- minimal repository admin access +- mandatory CI status checks before merge +- protected tags or release branches if releases are tag-driven + +This repository can document those requirements, but enforcement belongs in the source control platform. + +### 2. Build pipeline controls + +These controls establish that build outputs came from a trusted process. + +Recommended controls: + +- isolated build environment +- pinned builder images and actions +- least-privilege credentials for the build system +- artifact signing for produced container images or release assets +- provenance / attestation generation for builds +- immutable artifact storage or registry retention controls + +If you want image signing or provenance, that should usually live in the **build pipeline**, because that is where artifacts are actually created. + +### 3. Deploy pipeline controls + +These controls ensure only approved artifacts and manifests reach the cluster. + +Recommended controls: + +- verification of image signatures or attestations before deploy +- enforcement that deployment pulls only from approved registries +- promotion between environments using immutable digests rather than floating tags +- deployment-time policy checks for manifests and workload security settings +- manual approval or staged rollout where risk justifies it + +### 4. Runtime and cluster controls + +These controls reduce blast radius after deployment. + +Recommended controls: + +- namespace isolation and least-privilege RBAC +- workload security contexts +- non-root containers where possible +- dropped Linux capabilities +- read-only root filesystems where possible +- Kubernetes network policies +- admission control for workload standards +- runtime threat detection / alerting +- centralized logs, metrics, and alerts +- secrets delivery from a vault or equivalent system + +### 5. Recovery and resilience controls + +These controls matter because modern guidance assumes prevention will sometimes fail. + +Recommended controls: + +- tested rollback procedures +- backups and restore testing +- credential rotation procedures +- vulnerability remediation SLAs +- incident response playbooks +- inventory of critical services and owners + +## Recommended sibling pipeline responsibilities + +If you build a second pipeline to fill the gaps, keep the separation of concerns explicit. + +A sibling **build and deploy security pipeline** should be responsible for: + +- building artifacts in a trusted environment +- generating SBOMs tied to the built artifact +- signing artifacts +- generating provenance / attestations +- verifying signatures or attestations before deploy +- enforcing deploy-time policy on manifests and workloads +- optionally running DAST or post-deploy validation outside the fast PR loop + +That keeps this repository focused on source scanning while the sibling pipeline owns artifact trust and deployment trust. + +## Mapping this repository to modern security guidance + +A concise way to think about the split is: + +- **Assume compromise:** this repo helps by enforcing checks before deploy, but recovery and runtime containment live elsewhere. +- **Defense in depth:** this repo is one layer, not the whole system. +- **Blast-radius reduction:** this repo can reduce risky changes reaching production, but runtime RBAC, isolation, and network controls are outside its scope. +- **Zero trust / verified supply chain:** this repo contributes source and dependency scrutiny, but full artifact trust also needs build signing and deploy verification in another pipeline. +- **Prevention plus detection and recovery:** this repo is primarily a prevention and early-detection layer. + +## Minimum expectations for users of this repository + +If you adopt this repository, you should assume it is only one part of the security architecture. + +At minimum, you should also have: + +- repository branch protection and required reviews +- a secure build pipeline +- a deployment path that uses immutable artifacts +- workload hardening standards for deployed applications +- secret management outside Git +- logging/monitoring and a plan for response when a scanner finds something important + +## Non-goals + +To avoid scope creep, the following are non-goals for this repository: + +- becoming the authoritative runtime security platform +- becoming the artifact signing system +- becoming the deployment admission controller +- replacing source control platform protections +- replacing cluster hardening or incident response processes + +## Summary + +This repository is the **source-side security gate**. +It helps answer: "Is this code, IaC, dependency set, and generated SBOM safe enough to continue?" + +It does **not** answer the full downstream questions: + +- "Was the artifact built by a trusted builder?" +- "Should the cluster admit this artifact?" +- "Is the running workload isolated and monitored correctly?" +- "Can we detect, contain, and recover if prevention fails?" + +Those controls should exist, but they should live in adjacent repository, build, deploy, and runtime systems rather than being forced into this repository.