Skip to content

Commit 664730e

Browse files
aaronlippoldaaronlippold
committed
Project-wide updates for documentation and organization
- Added comprehensive documentation structure with theme and tools support - Reorganized workflow examples and improved file organization - Created extensive documentation infrastructure with MkDocs configuration - Added WCAG-compliant diagrams and styling - Implemented proper dark/light mode theme support - Added CI workflow for documentation deployment - Improved project organization and file structure - Expanded documentation for all scanning approaches Signed-off-by: Aaron Lippold <[email protected]>
1 parent 849a4a2 commit 664730e

File tree

82 files changed

+9680
-291
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

82 files changed

+9680
-291
lines changed

‎.gitattributes

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
docs/node_modules/* linguist-vendored
2+
docs/node_modules/* -diff -merge
3+
node_modules/* linguist-vendored
4+
node_modules/* -diff -merge

‎.github/workflows/deploy-docs.yml

+64
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
name: Deploy MkDocs
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
paths:
8+
- 'docs/**'
9+
- 'mkdocs.yml'
10+
- '.github/workflows/deploy-docs.yml'
11+
12+
permissions:
13+
contents: write
14+
15+
jobs:
16+
deploy:
17+
runs-on: ubuntu-latest
18+
steps:
19+
- uses: actions/checkout@v4
20+
with:
21+
fetch-depth: 0
22+
23+
# Set up Python and cache dependencies
24+
- name: Set up Python
25+
uses: actions/setup-python@v4
26+
with:
27+
python-version: 3.x
28+
cache: pip
29+
cache-dependency-path: docs/requirements.txt
30+
31+
# Install Python dependencies
32+
- name: Install Python dependencies
33+
run: |
34+
python -m pip install --upgrade pip
35+
pip install -r docs/requirements.txt
36+
37+
# Set up Node.js and cache dependencies
38+
- name: Set up Node.js
39+
uses: actions/setup-node@v3
40+
with:
41+
node-version: 18
42+
cache: npm
43+
cache-dependency-path: docs/package-lock.json
44+
45+
# Install Node.js dependencies
46+
- name: Install Node.js dependencies
47+
working-directory: ./docs
48+
run: npm ci || npm install
49+
50+
# Lint Markdown files (but don't fail the build)
51+
- name: Lint Markdown files
52+
working-directory: ./docs
53+
run: npm run lint || echo "Lint check skipped, continuing deployment"
54+
55+
# Build and validate documentation
56+
- name: Build documentation with validation
57+
run: mkdocs build --strict
58+
59+
# Deploy to GitHub Pages
60+
- name: Deploy documentation
61+
run: |
62+
git config --local user.email "github-actions[bot]@users.noreply.github.com"
63+
git config --local user.name "github-actions[bot]"
64+
mkdocs gh-deploy --force

‎.gitignore

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
node_modules/
2+
site/
3+
__pycache__/
4+
*.pyc
5+
.DS_Store
6+
venv/
7+
.venv/

‎CHANGELOG.md

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
docs/project/changelog.md

‎README.md

+76-14
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,9 @@ This project provides a comprehensive platform for securely scanning Kubernetes
66

77
Our solution offers three distinct technical approaches for container scanning:
88

9-
1. **Enhanced Transport Approach**: Modified train-k8s-container plugin for direct, API-based scanning through the Kubernetes management node
10-
2. **Debug Container Approach**: Ephemeral debug container with chroot-based scanning for distroless containers
11-
3. **Sidecar Container Approach**: CINC Auditor sidecar container with shared process namespace for any container type
9+
1. **Kubernetes API Approach** (Recommended): Direct API-based scanning through the Kubernetes API using the train-k8s-container plugin. This is our recommended enterprise solution with future distroless support in development, offering the most scalable and seamless integration. Once distroless support is implemented, this will be a universal solution for all container types.
10+
2. **Debug Container Approach**: Ephemeral debug container with chroot-based scanning for distroless containers, ideal for environments with ephemeral container support.
11+
3. **Sidecar Container Approach**: CINC Auditor sidecar container with shared process namespace for any container type, offering universal compatibility across Kubernetes versions.
1212

1313
These approaches can be deployed via:
1414
- Self-contained shell scripts for direct management and testing
@@ -42,19 +42,25 @@ Both approaches support:
4242

4343
We now provide three distinct approaches for scanning distroless containers:
4444

45-
1. **Ephemeral Debug Container** - Uses `kubectl debug` to attach a debug container and scan via chroot. This approach has some limitations:
45+
1. **Kubernetes API Approach** (Enterprise Recommended) - Enhanced train-k8s-container plugin for direct, API-based scanning:
46+
- **Implementation**: Currently being developed as our strategic enterprise solution
47+
- **Advantage**: No additional containers required, most efficient and scalable approach
48+
- **Advantage**: Seamless integration with existing CINC Auditor/InSpec workflows
49+
- **Advantage**: Transparent to users - same commands for both standard and distroless containers
50+
- **Key Advantage**: Will become a universal solution for all container types once distroless support is implemented
51+
- **Status**: In active development with high priority for enterprise environments
52+
53+
2. **Debug Container Approach** - Uses `kubectl debug` to attach a debug container and scan via chroot:
4654
- **Implementation**: The `scan-distroless-container.sh` script demonstrates this approach
4755
- **Limitation**: Requires Kubernetes clusters with ephemeral container support enabled
48-
49-
2. **Modified Transport Plugin** - Enhanced train-k8s-container plugin for direct, API-based scanning:
50-
- **Implementation**: Currently a work in progress
51-
- **Advantage**: No additional containers required, most efficient approach
56+
- **Use Case**: Best for testing and development environments with ephemeral container support
5257

5358
3. **Sidecar Container Approach** - Deploys a scanner sidecar in the same pod with shared process namespace:
5459
- **Implementation**: Fully implemented in `scan-with-sidecar.sh` and integrated with CI/CD examples
5560
- **Advantage**: Works with any Kubernetes cluster, requires no special features
5661
- **Advantage**: Can scan any container type, including distroless containers
5762
- **Limitation**: Must be deployed alongside the target container (can't scan existing containers)
63+
- **Use Case**: Ideal for environments without ephemeral container support or for universal compatibility
5864

5965
## Directory Structure
6066

@@ -308,30 +314,86 @@ failed:
308314
309315
## Documentation
310316
311-
For detailed documentation, see the following guides:
317+
### Online Documentation
318+
319+
Visit our comprehensive documentation at:
320+
321+
- https://mitre.github.io/kube-cinc-secure-scanner/
322+
323+
### Documentation Management
324+
325+
We provide a comprehensive documentation system in the `docs` directory with tools for previewing, validating, and improving documentation quality:
326+
327+
```bash
328+
# Navigate to the docs directory
329+
cd docs
330+
331+
# Make the script executable if needed
332+
chmod +x docs-tools.sh
333+
334+
# Preview documentation (background server)
335+
./docs-tools.sh preview
336+
337+
# Check server status
338+
./docs-tools.sh status
339+
340+
# Restart server
341+
./docs-tools.sh restart
342+
343+
# Stop server
344+
./docs-tools.sh stop
345+
346+
# Install all documentation dependencies
347+
./docs-tools.sh setup
348+
349+
# Lint and fix documentation issues
350+
./docs-tools.sh lint
351+
./docs-tools.sh fix
352+
353+
# Run comprehensive quality checks
354+
./docs-tools.sh check-all
355+
356+
# See all available commands
357+
./docs-tools.sh help
358+
```
359+
360+
The documentation system includes:
361+
- MkDocs with Material theme for beautiful documentation
362+
- Markdown style checking with markdownlint
363+
- Spell checking with pyspelling
364+
- Link validation with linkchecker
365+
- Comprehensive quality validation tools
366+
367+
For more details, see [Documentation Management](docs/README.md)
368+
369+
### Documentation Structure
370+
371+
Our documentation covers the following areas:
312372

313-
### Core Documentation
373+
#### Core Documentation
314374
- [Project Overview](docs/overview/README.md)
315375
- [Quick Start Guide](docs/overview/quickstart.md)
316376
- [Security Considerations](docs/overview/security.md)
377+
- [Executive Summary](docs/overview/executive-summary.md)
378+
- [Security Risk Analysis](docs/overview/security-risk-analysis.md)
317379

318-
### Approach-Specific Documentation
380+
#### Approach-Specific Documentation
319381
- [Distroless Container Scanning](docs/distroless-containers.md) - All three approaches compared
320382
- [Sidecar Container Approach](docs/sidecar-container-approach.md) - Detailed guide for Approach 3
321383

322-
### Visual Documentation
384+
#### Visual Documentation
323385
- [Workflow Diagrams](docs/overview/workflows.md) - Mermaid diagrams for visual environments
324386
- [ASCII Text Diagrams](docs/overview/ascii-diagrams.md) - Terminal-friendly diagrams
325387

326-
### Technical Implementation
388+
#### Technical Implementation
327389
- [RBAC Configuration](docs/rbac/README.md)
328390
- [Service Account Management](docs/service-accounts/README.md)
329391
- [Token Management](docs/tokens/README.md)
330392
- [Kubeconfig Generation](docs/configuration/README.md)
331393
- [SAF CLI Integration](docs/saf-cli-integration.md)
332394
- [Threshold Configuration](docs/thresholds.md)
333395

334-
### CI/CD Integration
396+
#### CI/CD Integration
335397
- [GitLab CI/CD Integration](docs/integration/gitlab.md)
336398
- [GitLab CI with Services](docs/integration/gitlab-services.md)
337399
- [GitHub Actions Integration](docs/integration/github-actions.md)

‎RELEASE-NOTES.md

+93
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# Release Notes - v1.0.0
2+
3+
## Secure CINC Auditor Kubernetes Container Scanning v1.0.0
4+
5+
We're excited to announce the first stable release of our Secure CINC Auditor Kubernetes Container Scanning platform. This release marks the culmination of extensive development to create a comprehensive, secure, and flexible solution for container compliance scanning in Kubernetes environments.
6+
7+
### Key Features
8+
9+
- **Three Container Scanning Approaches:**
10+
- Standard container scanning with train-k8s-container transport
11+
- Distroless container scanning via ephemeral debug containers
12+
- Sidecar container scanning with shared process namespace
13+
14+
- **Security-Focused Design:**
15+
- Least privilege RBAC configurations
16+
- Dynamic, time-limited access tokens
17+
- Fine-grained label-based access controls
18+
- Namespace isolation
19+
20+
- **Flexible Deployment Options:**
21+
- Self-contained shell scripts for direct usage
22+
- Modular Helm charts for enterprise deployment
23+
- CI/CD integration with GitHub Actions and GitLab CI
24+
25+
- **Comprehensive Documentation:**
26+
- MkDocs-based documentation site with enhanced navigation
27+
- Executive summary for stakeholders
28+
- Security risk analysis and mitigations
29+
- Approach decision matrix for informed selection
30+
- Enterprise integration analysis
31+
- Visual workflow diagrams and ASCII text diagrams
32+
33+
- **Integration Capabilities:**
34+
- MITRE SAF CLI for threshold validation
35+
- GitLab CI integration with services
36+
- GitHub Actions workflows
37+
- Comprehensive examples for all approaches
38+
39+
### What's Included
40+
41+
1. **Shell Scripts:**
42+
- `setup-minikube.sh` - Set up a test environment with multi-node minikube
43+
- `scan-container.sh` - Scan standard containers with CINC Auditor
44+
- `scan-distroless-container.sh` - Scan distroless containers with debug approach
45+
- `scan-with-sidecar.sh` - Scan containers using the sidecar approach
46+
- `generate-kubeconfig.sh` - Generate restricted kubeconfig files
47+
48+
2. **Helm Charts:**
49+
- `scanner-infrastructure` - Core RBAC, service accounts, tokens
50+
- `common-scanner` - Common scanning components and utilities
51+
- `standard-scanner` - Standard container scanning
52+
- `distroless-scanner` - Distroless container scanning
53+
- `sidecar-scanner` - Sidecar container scanning
54+
55+
3. **CI/CD Examples:**
56+
- GitHub Actions workflows for all scanning approaches
57+
- GitLab CI pipelines for all scanning approaches
58+
- GitLab CI with Services for optimized pipeline performance
59+
60+
4. **Documentation:**
61+
- Comprehensive MkDocs site with enhanced navigation
62+
- Full markdown documentation for all components
63+
- Visual workflow diagrams with Mermaid
64+
- ASCII text diagrams for terminal readability
65+
- Decision matrices and comparison guides
66+
67+
### Requirements
68+
69+
- Kubernetes 1.24+ (for token creation API)
70+
- kubectl
71+
- CINC Auditor with train-k8s-container plugin
72+
- MITRE SAF CLI (for threshold validation)
73+
- Helm 3.2.0+ (for Helm deployment)
74+
75+
For local documentation preview:
76+
- Python 3.x
77+
- MkDocs with Material theme (`pip install -r requirements.txt`)
78+
79+
### Future Development
80+
81+
- Complete the modified train-k8s-container plugin approach
82+
- Build and publish dedicated CINC Auditor scanner images
83+
- Create Kubernetes mutating webhook for sidecar injection
84+
- Add additional CI/CD platform examples
85+
- Enhance performance for large-scale scanning
86+
87+
### Acknowledgments
88+
89+
This project builds upon the work of:
90+
- CINC Project (open-source InSpec)
91+
- MITRE SAF CLI
92+
- train-k8s-container transport plugin
93+
- Kubernetes ephemeral containers feature

0 commit comments

Comments
 (0)