docs refining security scope

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.