Skip to content

Commit ad0d412

Browse files
karlllewistcpninja
karlllewis
and
tcpninja
authored
docs: add .editorconfig, compliance mapping, architecture overview, and link to README (#26)
Co-authored-by: tcpninja <cnciso@proton.me>
1 parent 2a7edcd commit ad0d412

11 files changed

Lines changed: 160 additions & 15 deletions

File tree

‎.editorconfig‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# .editorconfig
2+
root = true
3+
4+
[*]
5+
charset = utf-8
6+
end_of_line = lf
7+
insert_final_newline = true
8+
trim_trailing_whitespace = true
9+
indent_style = space
10+
indent_size = 2
11+
12+
[*.md]
13+
# Keep trailing spaces in markdown for deliberate line breaks
14+
trim_trailing_whitespace = false

‎.github/pull_request_template.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
## What
2-
-
2+
-
33

44
## Why
5-
-
5+
-
66

77
## How tested
88
- [ ] Local: `pre-commit` passes
99
- [ ] CI: Security workflow green on this branch
1010
- [ ] Screenshots / logs (optional):
11-
-
11+
-
1212

1313
## Risk & rollout
1414
- [ ] Backward compatible
@@ -27,4 +27,4 @@
2727
### Guardrails checklist (automated)
2828
- Pre-commit: **Gitleaks** blocks secrets locally
2929
- CI: **Trivy** uploads SARIF to Code Scanning
30-
- CI: **SBOM** artifact (spdx) published on each run
30+
- CI: **SBOM** artifact (spdx) published on each run

‎.github/workflows/scorecard.yml‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,4 +35,3 @@ jobs:
3535
uses: github/codeql-action/upload-sarif@v3
3636
with:
3737
sarif_file: results.sarif
38-

‎.github/workflows/security.yml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
name: security
22

3-
on:
3+
on:
44
pull_request:
55
push:
66
branches:
77
- main
88
workflow_dispatch:
9-
9+
1010
permissions:
1111
contents: read
1212
security-events: write # needed to upload SARIF
@@ -22,7 +22,7 @@ jobs:
2222
steps:
2323
- name: Checkout
2424
uses: actions/checkout@v5
25-
25+
2626
# === Optional: Install Trivy CLI ===
2727
# Github's ubuntu-latest runner currently has Trivy pre-installed
2828
# Uncomment this if using a custom runner or if you need to pin a specific version

‎.gitignore‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
.DS_Store
22
*.log
33
sbom.spdx.json
4-
reports/
4+
reports/

‎README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -179,6 +179,9 @@ For executive stakeholders and security reviewers, we maintain a concise
179179
- Policy exception workflow
180180
- Security contact information
181181

182+
- **Compliance mapping:** see [docs/compliance-mapping.md](./docs/compliance-mapping.md)
183+
- **Architecture overview:** see [docs/architecture.md](./docs/architecture.md)
184+
182185
---
183186

184187
## Roadmap

‎SECURITY.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ Instead, email: **cnciso@proton.me** with:
1717

1818
We aim to acknowledge reports **within 72 hours** and provide a remediation plan or timeline as soon as reasonably possible.
1919

20-
If you prefer GitHub, you may open a **private** security advisory via:
20+
If you prefer GitHub, you may open a **private** security advisory via:
2121
**Security → Advisories → Report a vulnerability** (in this repository).
2222

2323
## Disclosure Process
@@ -34,4 +34,4 @@ This starter provides:
3434
It does **not** replace full threat modeling, runtime controls, or a team of trained security professionals. For production workloads, pair this with:
3535
- Image signing & provenance (Sigstore/SLSA)
3636
- Admission controls / policy-as-code (e.g., Kyverno)
37-
- Runtime hardening (e.g., seccomp, apparmor, eBPF)
37+
- Runtime hardening (e.g., seccomp, apparmor, eBPF)

‎docs/architecture.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# Secure-by-Default Starter: Architecture Overview
2+
3+
This document describes the architecture, controls, and evidence flow of the Secure-by-Default Starter.
4+
5+
---
6+
7+
## Legend & Assumptions
8+
9+
**Legend**
10+
- Solid arrow: normal flow
11+
- Dashed arrow: visibility/evidence
12+
- 🔒 = security control
13+
- 📦 = artifact
14+
15+
**Assumptions**
16+
- GitHub Actions runners (ubuntu-latest)
17+
- Docker available for local parity (`make scan`, `make sbom`)
18+
- No GitHub Advanced Security required (works on Free); complements it if enabled
19+
20+
---
21+
22+
## Flow Overview
23+
24+
```mermaid
25+
flowchart TD
26+
Dev[Developer Laptop] -->|git push| Repo[(GitHub Repo)]
27+
Repo -->|CI Trigger| Actions[GitHub Actions]
28+
Actions -->|Trivy fs scan| TrivyScanner[Trivy 🔒]
29+
Actions -->|Generate SBOM| SBOM[SPDX 📦]
30+
Actions -->|Upload SARIF| SARIF[Code Scanning Alerts 📦]
31+
Repo -.->|Branch Protection| PR[Pull Request Checks 🔒]
32+
SBOM -->|Artifact| GHArtifacts[GitHub Artifacts 📦]
33+
```
34+
35+
---
36+
37+
## Sequence View
38+
39+
```mermaid
40+
sequenceDiagram
41+
autonumber
42+
participant Dev as Developer
43+
participant Repo as GitHub Repo
44+
participant CI as GitHub Actions
45+
participant Trivy as Trivy Scanner
46+
participant GHSec as Code Scanning (SARIF)
47+
participant Art as Artifacts (SBOM)
48+
49+
Dev->>Dev: pre-commit (🔒 Gitleaks) blocks secrets
50+
Dev->>Repo: push branch / open PR
51+
Repo-->>CI: trigger security workflow
52+
CI->>Trivy: fs scan (vuln + IaC) with HIGH/CRIT gate
53+
Trivy-->>CI: results (exit-code 0/1)
54+
CI->>GHSec: upload SARIF (📦 evidence)
55+
CI->>Art: publish sbom.spdx.json (📦 evidence)
56+
CI-->>Repo: status checks (pass/fail gate)
57+
```
58+
59+
---
60+
61+
## Components & Responsibilities
62+
63+
| Component | Responsibility | Evidence Produced |
64+
|---|---|---|
65+
| Pre-commit (Gitleaks) 🔒 | Stop hardcoded secrets before push | Local terminal output; blocked commit |
66+
| Trivy (CI) 🔒 | Vulnerability + IaC misconfig scan; fail on HIGH/CRIT | SARIF uploaded to Code scanning |
67+
| SBOM step 📦 | Generate SPDX JSON of repo dependencies/assets | `sbom.spdx.json` artifact in Actions |
68+
| Branch Protection 🔒 | Enforce PR review & passing checks | Protected branch status |
69+
| Dependabot | Open dependency update PRs | PRs labeled `dependencies` |
70+
| OpenSSF Scorecard | External hygiene signal | Public score/badge |
71+
| Trust Page | Single place to find status & evidence | `docs/trust-page.md` |
72+
73+
---
74+
75+
## Threat Model (Starter)
76+
77+
**Assets**
78+
- Source code (confidentiality/integrity)
79+
- SBOM + SARIF artifacts (integrity)
80+
- Secret material (must never enter repo)
81+
82+
**Key Risks & Controls**
83+
- Secret leakage → 🔒 pre-commit Gitleaks blocks locally
84+
- Vulnerabilities / misconfigs → 🔒 Trivy CI gate on HIGH/CRIT
85+
- Unreviewed/unsafe merges → 🔒 Branch protection + required checks
86+
- Supply-chain drift → Dependabot weekly updates; SBOM per run
87+
- Lack of evidence for auditors → SARIF in Code scanning + SPDX artifact + Trust page
88+
89+
---
90+
91+
## Evidence Retention & Privacy
92+
93+
- **Artifacts**: `sbom.spdx.json` retained per Actions retention policy (repo setting).
94+
- **SARIF alerts**: stored in GitHub Security → Code scanning.
95+
- **No secrets**: baseline prevents secrets from entering history; rotate immediately if detected locally.
96+
97+
---
98+
99+
## Extensibility
100+
101+
- **Supply chain**: Cosign/SLSA attestations → after SBOM step.
102+
- **Kubernetes policy**: Kyverno/Conftest → additional CI job; optional PR annotations.
103+
- **AI/LLM repos**: add model/package scanners (e.g., known-bad weights/licenses) → new job, same gating model.
104+
- **GitHub Advanced Security**: enable Push Protection, CodeQL → complements Trivy; keep both.
105+
106+
---
107+
108+
## Controls Matrix (Quick Map)
109+
110+
| Risk | Control | Where |
111+
|---|---|---|
112+
| Secrets in commits | 🔒 Gitleaks pre-commit | Developer laptop |
113+
| Critical CVEs | 🔒 Trivy gate HIGH/CRIT | CI |
114+
| IaC misconfig | 🔒 Trivy config scanner | CI |
115+
| Unknown assets | 📦 SPDX SBOM per run | CI Artifacts |
116+
| Unreviewed merge | 🔒 Branch protection | Repo settings |
117+
| Stale deps | Dependabot weekly PRs | GitHub PRs |

‎docs/compliance-mapping.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Compliance Mapping (Starter 80/20)
2+
3+
This repo provides a starter mapping between security guardrails and compliance frameworks.
4+
5+
| Control Theme | What this repo provides | Maps to |
6+
|-----------------------|--------------------------------------------------|----------------------------------|
7+
| **Secrets handling** | Pre-commit Gitleaks; blocks tokens pre-push | SOC2 CC6.1/CC6.6, ISO 27001 8.2 |
8+
| **Vulnerability mgmt**| Trivy CI + fail on HIGH/CRIT findings | SOC2 CC7.1, ISO 27001 12.6 |
9+
| **Asset transparency**| SBOM (SPDX) artifact per build | SOC2 CC8.1, ISO 27001 8.1 |
10+
| **IaC hygiene** | Trivy IaC misconfiguration scan | SOC2 CC7.2, ISO 27001 14.2 |
11+
12+
> Note: This is a pragmatic starter. Extend with NIST CSF, CIS Benchmarks, and org-specific controls as needed.

‎examples/Dockerfile.good‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
1-
# Secure example: pinned, small, non-root
1+
# Secure example: pinned, small, non-root
22
# Smaller base images = smaller attack surface
33
FROM nginx:1.29.1-alpine
4-
# Create an unprivileged user and use it.
4+
# Create an unprivileged user and use it.
55
RUN adduser -D -u 10001 appuser
66
USER 10001:10001
77
# Default nginx starts as this user in alpine variant
88

99
# Run on an unpriveleged port (>1024) so we don't need NET_BIND_SERVICE
1010
EXPOSE 8080
1111

12-
# We can improve this Dockerfile quite a bit, but I want to keep it simple for now
12+
# We can improve this Dockerfile quite a bit, but I want to keep it simple for now

0 commit comments

Comments
 (0)