208 lines
8.8 KiB
Markdown
208 lines
8.8 KiB
Markdown
# 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.
|