Fix build and code structure improvements. New but essential UI functionality. CI improvements. Documentation improvements. AI module improvements.
This commit is contained in:
StellaOps Bot
508
docs/cicd/security-scanning.md
Normal file
508
docs/cicd/security-scanning.md
Normal file
@@ -0,0 +1,508 @@
|
||||
# Security Scanning
|
||||
|
||||
> Complete guide to security scanning workflows in the StellaOps CI/CD pipeline.
|
||||
|
||||
---
|
||||
|
||||
## Security Scanning Overview
|
||||
|
||||
StellaOps implements a **defense-in-depth** security scanning strategy:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ SECURITY SCANNING LAYERS │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Layer 1: PRE-COMMIT │
|
||||
│ └── Secrets scanning (pre-commit hook) │
|
||||
│ │
|
||||
│ Layer 2: PULL REQUEST │
|
||||
│ ├── SAST (Static Application Security Testing) │
|
||||
│ ├── Secrets scanning │
|
||||
│ ├── Dependency vulnerability audit │
|
||||
│ └── License compliance check │
|
||||
│ │
|
||||
│ Layer 3: MAIN BRANCH │
|
||||
│ ├── All Layer 2 scans │
|
||||
│ ├── Container image scanning │
|
||||
│ └── Extended SAST analysis │
|
||||
│ │
|
||||
│ Layer 4: SCHEDULED │
|
||||
│ ├── Weekly deep SAST scan (Monday) │
|
||||
│ ├── Weekly dependency audit (Sunday) │
|
||||
│ ├── Daily container scanning │
|
||||
│ └── Nightly regression security tests │
|
||||
│ │
|
||||
│ Layer 5: RELEASE │
|
||||
│ ├── Final vulnerability gate │
|
||||
│ ├── SBOM generation and signing │
|
||||
│ ├── Provenance attestation │
|
||||
│ └── Container signing │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Scanning Workflows
|
||||
|
||||
### 1. SAST Scanning (`sast-scan.yml`)
|
||||
|
||||
**Purpose:** Detect security vulnerabilities in source code through static analysis.
|
||||
|
||||
**Triggers:**
|
||||
- Pull requests (source code changes)
|
||||
- Push to main/develop
|
||||
- Weekly Monday 3:30 AM UTC
|
||||
- Manual dispatch
|
||||
|
||||
**Scanned Languages:**
|
||||
- C# / .NET
|
||||
- JavaScript / TypeScript
|
||||
- Python
|
||||
- YAML
|
||||
- Dockerfile
|
||||
|
||||
**Checks Performed:**
|
||||
|
||||
| Check | Tool | Scope |
|
||||
|-------|------|-------|
|
||||
| Code vulnerabilities | Semgrep/CodeQL (placeholder) | All source |
|
||||
| .NET security analyzers | Built-in Roslyn | C# code |
|
||||
| Dependency vulnerabilities | `dotnet list --vulnerable` | NuGet packages |
|
||||
| Dockerfile best practices | Hadolint | Dockerfiles |
|
||||
|
||||
**Configuration:**
|
||||
|
||||
```yaml
|
||||
# sast-scan.yml inputs
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
scan_level:
|
||||
type: choice
|
||||
options:
|
||||
- quick # Fast scan, critical issues only
|
||||
- standard # Default, balanced coverage
|
||||
- comprehensive # Full scan, all rules
|
||||
fail_on_findings:
|
||||
type: boolean
|
||||
default: true # Block on findings
|
||||
```
|
||||
|
||||
**.NET Security Analyzer Rules:**
|
||||
|
||||
The workflow enforces these security-critical CA rules as errors:
|
||||
|
||||
| Category | Rules | Description |
|
||||
|----------|-------|-------------|
|
||||
| SQL Injection | CA2100 | Review SQL queries for vulnerabilities |
|
||||
| Cryptography | CA5350-5403 | Weak crypto, insecure algorithms |
|
||||
| Deserialization | CA2300-2362 | Unsafe deserialization |
|
||||
| XML Security | CA3001-3012 | XXE, XPath injection |
|
||||
| Web Security | CA3061, CA5358-5398 | XSS, CSRF, CORS |
|
||||
|
||||
---
|
||||
|
||||
### 2. Secrets Scanning (`secrets-scan.yml`)
|
||||
|
||||
**Purpose:** Detect hardcoded credentials, API keys, and secrets in code.
|
||||
|
||||
**Triggers:**
|
||||
- Pull requests
|
||||
- Push to main/develop
|
||||
- Manual dispatch
|
||||
|
||||
**Detection Patterns:**
|
||||
|
||||
| Secret Type | Example Pattern |
|
||||
|-------------|-----------------|
|
||||
| API Keys | `sk_live_[a-zA-Z0-9]+` |
|
||||
| AWS Keys | `AKIA[0-9A-Z]{16}` |
|
||||
| Private Keys | `-----BEGIN RSA PRIVATE KEY-----` |
|
||||
| Connection Strings | `Password=.*;User ID=.*` |
|
||||
| JWT Tokens | `eyJ[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+` |
|
||||
| GitHub Tokens | `gh[ps]_[A-Za-z0-9]{36}` |
|
||||
|
||||
**Tool Options (Placeholder):**
|
||||
|
||||
```yaml
|
||||
# Choose one by uncommenting in sast-scan.yml:
|
||||
|
||||
# Option 1: TruffleHog (recommended for open source)
|
||||
# - name: TruffleHog Scan
|
||||
# uses: trufflesecurity/trufflehog@main
|
||||
# with:
|
||||
# extra_args: --only-verified
|
||||
|
||||
# Option 2: Gitleaks
|
||||
# - name: Gitleaks Scan
|
||||
# uses: gitleaks/gitleaks-action@v2
|
||||
# env:
|
||||
# GITLEAKS_LICENSE: ${{ secrets.GITLEAKS_LICENSE }}
|
||||
|
||||
# Option 3: Semgrep
|
||||
# - name: Semgrep Secrets
|
||||
# uses: returntocorp/semgrep-action@v1
|
||||
# with:
|
||||
# config: p/secrets
|
||||
```
|
||||
|
||||
**Allowlist Configuration:**
|
||||
|
||||
Create `.gitleaksignore` or `.secretsignore` for false positives:
|
||||
|
||||
```
|
||||
# Ignore test fixtures
|
||||
src/__Tests/**/*
|
||||
docs/examples/**/*
|
||||
|
||||
# Ignore specific files
|
||||
path/to/test-credentials.json
|
||||
|
||||
# Ignore by rule ID
|
||||
[allowlist]
|
||||
regexes = ["test_api_key_[a-z]+"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. Container Scanning (`container-scan.yml`)
|
||||
|
||||
**Purpose:** Scan container images for OS and application vulnerabilities.
|
||||
|
||||
**Triggers:**
|
||||
- Dockerfile changes
|
||||
- Daily schedule (4 AM UTC)
|
||||
- Manual dispatch
|
||||
|
||||
**Scan Targets:**
|
||||
|
||||
| Image | Built From | Scanned Components |
|
||||
|-------|------------|-------------------|
|
||||
| `stellaops/authority` | `src/Authority/Dockerfile` | OS packages, .NET runtime |
|
||||
| `stellaops/scanner` | `src/Scanner/Dockerfile` | OS packages, .NET runtime, analyzers |
|
||||
| `stellaops/concelier` | `src/Concelier/Dockerfile` | OS packages, .NET runtime |
|
||||
| (9 total images) | ... | ... |
|
||||
|
||||
**Vulnerability Severity Levels:**
|
||||
|
||||
| Severity | Action | Example |
|
||||
|----------|--------|---------|
|
||||
| CRITICAL | Block release | Remote code execution |
|
||||
| HIGH | Block release (configurable) | Privilege escalation |
|
||||
| MEDIUM | Warning | Information disclosure |
|
||||
| LOW | Log only | Minor issues |
|
||||
| UNKNOWN | Log only | Unclassified |
|
||||
|
||||
**Tool Options (Placeholder):**
|
||||
|
||||
```yaml
|
||||
# Choose one by uncommenting in container-scan.yml:
|
||||
|
||||
# Option 1: Trivy (recommended)
|
||||
# - name: Trivy Scan
|
||||
# uses: aquasecurity/trivy-action@master
|
||||
# with:
|
||||
# image-ref: ${{ steps.build.outputs.image }}
|
||||
# format: sarif
|
||||
# output: trivy-results.sarif
|
||||
# severity: CRITICAL,HIGH
|
||||
|
||||
# Option 2: Grype
|
||||
# - name: Grype Scan
|
||||
# uses: anchore/scan-action@v3
|
||||
# with:
|
||||
# image: ${{ steps.build.outputs.image }}
|
||||
# fail-build: true
|
||||
# severity-cutoff: high
|
||||
|
||||
# Option 3: Snyk Container
|
||||
# - name: Snyk Container
|
||||
# uses: snyk/actions/docker@master
|
||||
# env:
|
||||
# SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. Dependency Security Scanning (`dependency-security-scan.yml`)
|
||||
|
||||
**Purpose:** Audit NuGet and npm packages for known vulnerabilities.
|
||||
|
||||
**Triggers:**
|
||||
- Weekly Sunday 2 AM UTC
|
||||
- Pull requests (dependency file changes)
|
||||
- Manual dispatch
|
||||
|
||||
**Scanned Files:**
|
||||
|
||||
| Ecosystem | Files |
|
||||
|-----------|-------|
|
||||
| NuGet | `src/Directory.Packages.props`, `**/*.csproj` |
|
||||
| npm | `**/package.json`, `**/package-lock.json` |
|
||||
|
||||
**Vulnerability Sources:**
|
||||
|
||||
- GitHub Advisory Database
|
||||
- NVD (National Vulnerability Database)
|
||||
- OSV (Open Source Vulnerabilities)
|
||||
- Vendor security advisories
|
||||
|
||||
**Scan Process:**
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ DEPENDENCY SECURITY SCAN │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌──────────────┐ │
|
||||
│ │ scan-nuget │ dotnet list package --vulnerable │
|
||||
│ └──────┬───────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌──────────────┐ │
|
||||
│ │ scan-npm │ npm audit --json │
|
||||
│ └──────┬───────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌──────────────┐ │
|
||||
│ │ summary │ Aggregate results, generate report │
|
||||
│ └──────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Example Output:**
|
||||
|
||||
```
|
||||
## Dependency Vulnerability Audit
|
||||
|
||||
### NuGet Packages
|
||||
| Package | Installed | Vulnerable | Severity | Advisory |
|
||||
|---------|-----------|------------|----------|----------|
|
||||
| Newtonsoft.Json | 12.0.1 | < 13.0.1 | HIGH | GHSA-xxxx |
|
||||
|
||||
### npm Packages
|
||||
| Package | Installed | Vulnerable | Severity | Advisory |
|
||||
|---------|-----------|------------|----------|----------|
|
||||
| lodash | 4.17.15 | < 4.17.21 | CRITICAL | npm:lodash:1 |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. License Compliance (`dependency-license-gate.yml`)
|
||||
|
||||
**Purpose:** Ensure all dependencies use approved licenses.
|
||||
|
||||
**Approved Licenses:**
|
||||
|
||||
| License | SPDX ID | Status |
|
||||
|---------|---------|--------|
|
||||
| MIT | MIT | Approved |
|
||||
| Apache 2.0 | Apache-2.0 | Approved |
|
||||
| BSD 2-Clause | BSD-2-Clause | Approved |
|
||||
| BSD 3-Clause | BSD-3-Clause | Approved |
|
||||
| ISC | ISC | Approved |
|
||||
| MPL 2.0 | MPL-2.0 | Review Required |
|
||||
| LGPL 2.1+ | LGPL-2.1-or-later | Review Required |
|
||||
| GPL 2.0+ | GPL-2.0-or-later | Blocked (copyleft) |
|
||||
| AGPL 3.0 | AGPL-3.0 | Blocked (copyleft) |
|
||||
|
||||
**Blocked on Violation:**
|
||||
- GPL-licensed runtime dependencies
|
||||
- Unknown/proprietary licenses without explicit approval
|
||||
|
||||
---
|
||||
|
||||
## Scan Results & Reporting
|
||||
|
||||
### GitHub Step Summary
|
||||
|
||||
All security scans generate GitHub Step Summary reports:
|
||||
|
||||
```markdown
|
||||
## SAST Scan Summary
|
||||
|
||||
| Check | Status |
|
||||
|-------|--------|
|
||||
| SAST Analysis | ✅ Pass |
|
||||
| .NET Security | ⚠️ 3 warnings |
|
||||
| Dependency Check | ✅ Pass |
|
||||
| Dockerfile Lint | ✅ Pass |
|
||||
|
||||
### .NET Security Warnings
|
||||
- CA5350: Weak cryptographic algorithm (src/Crypto/Legacy.cs:42)
|
||||
- CA2100: SQL injection risk (src/Data/Query.cs:78)
|
||||
```
|
||||
|
||||
### SARIF Integration
|
||||
|
||||
Scan results are uploaded in SARIF format for IDE integration:
|
||||
|
||||
```yaml
|
||||
- name: Upload SARIF
|
||||
uses: github/codeql-action/upload-sarif@v3
|
||||
with:
|
||||
sarif_file: scan-results.sarif
|
||||
```
|
||||
|
||||
### Artifact Retention
|
||||
|
||||
| Artifact | Retention |
|
||||
|----------|-----------|
|
||||
| SARIF files | 30 days |
|
||||
| Vulnerability reports | 90 days |
|
||||
| License audit logs | 1 year |
|
||||
|
||||
---
|
||||
|
||||
## Security Gates
|
||||
|
||||
### PR Merge Requirements
|
||||
|
||||
| Gate | Threshold | Block Merge? |
|
||||
|------|-----------|--------------|
|
||||
| SAST Critical | 0 | Yes |
|
||||
| SAST High | 0 | Configurable |
|
||||
| Secrets Found | 0 | Yes |
|
||||
| Vulnerable Dependencies (Critical) | 0 | Yes |
|
||||
| Vulnerable Dependencies (High) | 5 | Warning |
|
||||
| License Violations | 0 | Yes |
|
||||
|
||||
### Release Requirements
|
||||
|
||||
| Gate | Threshold | Block Release? |
|
||||
|------|-----------|----------------|
|
||||
| Container Scan (Critical) | 0 | Yes |
|
||||
| Container Scan (High) | 0 | Yes |
|
||||
| SBOM Generation | Success | Yes |
|
||||
| Signature Verification | Valid | Yes |
|
||||
|
||||
---
|
||||
|
||||
## Remediation Workflows
|
||||
|
||||
### Dependency Vulnerability Fix
|
||||
|
||||
1. **Renovate Auto-Fix:**
|
||||
```yaml
|
||||
# renovate.json
|
||||
{
|
||||
"vulnerabilityAlerts": {
|
||||
"enabled": true,
|
||||
"labels": ["security"],
|
||||
"automerge": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. **Manual Override:**
|
||||
```bash
|
||||
# Update specific package
|
||||
dotnet add package Newtonsoft.Json --version 13.0.3
|
||||
|
||||
# Audit and fix npm
|
||||
npm audit fix
|
||||
```
|
||||
|
||||
### False Positive Suppression
|
||||
|
||||
**.NET Analyzer Suppression:**
|
||||
|
||||
```csharp
|
||||
// Suppress specific instance
|
||||
#pragma warning disable CA2100 // Review SQL queries for vulnerability
|
||||
var query = $"SELECT * FROM {tableName}";
|
||||
#pragma warning restore CA2100
|
||||
|
||||
// Or in .editorconfig
|
||||
[*.cs]
|
||||
dotnet_diagnostic.CA2100.severity = none # NOT RECOMMENDED
|
||||
```
|
||||
|
||||
**Semgrep/SAST Suppression:**
|
||||
|
||||
```csharp
|
||||
// nosemgrep: sql-injection
|
||||
var query = $"SELECT * FROM {tableName}";
|
||||
```
|
||||
|
||||
**Container Scan Ignore:**
|
||||
|
||||
```yaml
|
||||
# .trivyignore
|
||||
CVE-2021-44228 # Log4j - not applicable (no Java)
|
||||
CVE-2022-12345 # Accepted risk with mitigation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuration Files
|
||||
|
||||
### Location
|
||||
|
||||
| File | Purpose | Location |
|
||||
|------|---------|----------|
|
||||
| `.gitleaksignore` | Secrets scan allowlist | Repository root |
|
||||
| `.trivyignore` | Container scan ignore list | Repository root |
|
||||
| `.semgrepignore` | SAST ignore patterns | Repository root |
|
||||
| `renovate.json` | Dependency update config | Repository root |
|
||||
| `.editorconfig` | Analyzer severity | Repository root |
|
||||
|
||||
### Example `.trivyignore`
|
||||
|
||||
```
|
||||
# Ignore by CVE ID
|
||||
CVE-2021-44228
|
||||
|
||||
# Ignore by package
|
||||
pkg:npm/lodash@4.17.15
|
||||
|
||||
# Ignore with expiration
|
||||
CVE-2022-12345 exp:2025-06-01
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Scheduled Scan Summary
|
||||
|
||||
| Day | Time (UTC) | Workflow | Focus |
|
||||
|-----|------------|----------|-------|
|
||||
| Daily | 2:00 AM | `nightly-regression.yml` | Security tests |
|
||||
| Daily | 4:00 AM | `container-scan.yml` | Image vulnerabilities |
|
||||
| Sunday | 2:00 AM | `dependency-security-scan.yml` | Package audit |
|
||||
| Monday | 3:30 AM | `sast-scan.yml` | Deep code analysis |
|
||||
|
||||
---
|
||||
|
||||
## Monitoring & Alerts
|
||||
|
||||
### Notification Channels
|
||||
|
||||
Configure notifications for security findings:
|
||||
|
||||
```yaml
|
||||
# In workflow
|
||||
- name: Notify on Critical
|
||||
if: steps.scan.outputs.critical_count > 0
|
||||
run: |
|
||||
curl -X POST "${{ secrets.SLACK_WEBHOOK }}" \
|
||||
-d '{"text":"🚨 Critical security finding in '${{ github.repository }}'"}'
|
||||
```
|
||||
|
||||
### Dashboard Integration
|
||||
|
||||
Security scan results can be exported to:
|
||||
- Grafana dashboards (via OTLP metrics)
|
||||
- Security Information and Event Management (SIEM)
|
||||
- Vulnerability management platforms
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [README - CI/CD Overview](./README.md)
|
||||
- [Workflow Triggers](./workflow-triggers.md)
|
||||
- [Release Pipelines](./release-pipelines.md)
|
||||
- [Dependency Management](../operations/dependency-management.md)
|
||||
- [SBOM Guide](../sbom/guide.md)
|
||||
Reference in New Issue
Block a user