Skip to content

About

Containerized open-source collaboration tools for deployment on cloud.gov (GSA-TTS)

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

Β 

History

59 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

Collaboration Containers for Deployment on cloud.gov

A collection of containerized open-source collaboration tools, optimized for deployment on cloud.gov with security scanning and two deployment options (from GHCR registry or local build).

Status: Public-release preparation is in progress. Current-file lint, Dockerfile lint, Trivy filesystem scan, and working-tree secret scanning pass. Historical Gitleaks findings have documented, fingerprint-scoped acceptance. Release workflow verification, GitHub repository configuration, and required sign-offs are still required before making the repository public.

πŸš€ Quick Start

For Users (Deploy Pre-Built Image)

# Pull and run (fastest, recommended for most users)
docker pull ghcr.io/gsa-tts/hedgedoc:v1.0.0
docker run -it ghcr.io/gsa-tts/hedgedoc:v1.0.0

For Developers (Build Locally)

# Install mise (tool runner)
curl https://mise.jdx.dev/install.sh | sh

# Clone, build, and scan
git clone https://github.com/GSA-TTS/collab-containers.git
cd collab-containers
mise run container:build-all   # Build with security scanning
mise run scan:all              # Run all security checks

πŸ“– Important Documentation

Document For Purpose
PUBLIC_RELEASE_GUIDE.md Everyone Overview of current capabilities, options, and remaining blockers
DEPLOYMENT.md Operators Complete deployment guide: registry vs local build, security, production checklist
SECURITY.md Security teams Vulnerability reporting, scanning practices, compliance standards
PUBLIC_READINESS_CHECKLIST.md Release managers 100+ checklist items before public release, sign-off tracking
mise.toml Developers 30+ runnable tasks for security scanning, building, signing containers

Start here: PUBLIC_RELEASE_GUIDE.md

Deployment Status

App Status Auth Proxy Recommended Last Failure (if any) Directory Link
Marimo βœ… Working βœ… Yes (oauth2-proxy) marimo
openvscode-server βœ… Working βœ… Yes (oauth2-proxy) openVScode
Excalidraw βœ… Working βœ… Yes (oauth2-proxy) excalidraw
HedgeDoc βœ… Working 🚫 Not used (direct UAA OAuth2) hedgedoc
Outline ❌ Failing 🚫 Required (oauth2-proxy) GSA WAF blocks /api/auth.config with a 403 (dot-config block rule). outline
Planka ❌ Failing 🚫 Required (oauth2-proxy) Database resolved, but Cloud.gov SAML split-domain session cookie is stripped by browser (SameSite block). planka
CryptPad βœ… Working βœ… Yes (oauth2-proxy) cryptpad
Backstage βœ… Working βœ… Yes (oauth2-proxy) backstage
Auth proxy benchmark πŸ§ͺ Experimental β€” Cloud.gov UAA benchmark harness and proxy manifests. auth-benchmark

Others?

Create an Issue or Open a PR

Steps to Deploy

  1. Ensure you have the Cloud Foundry CLI installed and are logged into your cloud.gov account.
  2. Navigate to this folder in your terminal.
  3. Run the following command to deploy:
    cf login -a api.fr.cloud.gov --sso
    cd app-name  # Replace with the specific app folder, e.g., `hedgedoc`
    cf push
  4. Access the application at the domain specified in the CMD_DOMAIN environment variable.

Mise Tasks (Local Development)

Run security checks and build tasks using mise:

# Security & Compliance
mise run scan:all               # All security scans
mise run scan:secrets           # Gitleaks secret detection
mise run scan:dockerfile        # Hadolint linting
mise run scan:trivy-fs          # Trivy filesystem scan
mise run scan:trivy-container   # Trivy image scan

# Container Building
mise run container:build-all    # Build all images
mise run container:inspect      # Inspect built image

# SBOM & Signing
mise run sbom:generate          # Generate SPDX + CycloneDX
mise run sign:cosign-keygen     # Generate signing keys
mise run sign:cosign-image      # Sign container image

# CI/CD
mise run ci:pre-release-check   # Pre-release verification

# Help
mise run help:security          # Security scanning guide
mise run help:deployment        # Deployment options guide

See mise.toml for all 30+ available tasks.


Benchmarking Auth Proxies

Use auth-benchmark to compare UAA-backed auth proxies in front of fixture apps or any of the deployed collaboration containers in this repository.

Container Publishing and Findings

This repository includes GitHub Actions workflows to discover every top-level Dockerfile, build each container image, scan it with Trivy, and publish it to ghcr.io.

  • publish-containers.yml runs on published GitHub releases or manual dispatch.
  • Each discovered container is pushed to ghcr.io/<owner>/<container>:<version> and :latest.
  • Trivy findings are saved as workflow artifacts and attached to each per-container release as a SARIF report, with SPDX and CycloneDX SBOMs.
  • The workflow creates a GitHub Release per container, using tags like <container>-v1.2.3, and attaches the Trivy and SBOM reports.

How to use it

  1. Ensure Actions have permission to write packages and contents in the repository settings.
  2. Publish a repository release with a tag like v1.2.3, or run the workflow manually and provide 1.2.3 as release_version.
  3. Review findings in the workflow artifacts and in the per-container GitHub Releases.

Container Publishing and Security Scanning

This repository includes automated GitHub Actions workflows that:

  1. Discover every top-level Dockerfile
  2. Build each container image
  3. Scan with multiple tools:
    • Trivy β€” Vulnerability, configuration, and secret scanning (SARIF)
  4. Generate Software Bill of Materials (SBOM)
    • SPDX format (industry standard)
    • CycloneDX format (OWASP standard)
  5. Publish to GitHub Container Registry (GHCR)
  6. Attach security reports to GitHub Releases

Scanning Details

Trivy Scanning:

  • Vulnerability detection (HIGH/CRITICAL severity)
  • Configuration best practices
  • Secret detection in images
  • SARIF format for GitHub Security tab integration

SBOM Generation:

  • All dependencies documented with versions
  • Two formats for different compliance needs
  • Transparency for software supply chain

Using Published Images

  1. Navigate to Releases
  2. Download security reports:
    • trivy-vulnerability-scan.sarif
    • sbom-spdx.json / sbom-cyclonedx.json
  3. Review findings before production deployment
  4. Deploy after reviewing reports using docker pull ghcr.io/gsa-tts/<app>:<version>

How to Create a Release

  1. Ensure GitHub Actions have permission to write packages and contents
  2. Publish a GitHub release with a shared tag like v1.0.0
  3. Or run publish-containers.yml manually with version 1.0.0
  4. Review findings in workflow artifacts and per-container GitHub Release

CI/CD Integration

  • Container Scan on PR (container-scan-on-pr.yml)

    • Runs on Dockerfile/init.sh changes
    • Trivy scans
    • Reports in artifacts and GitHub Security tab
  • Publish on Release (publish-containers.yml)

    • Runs on GitHub release publish
    • Builds, scans, and publishes images
    • Attaches comprehensive security reports
    • Creates per-container release tags

Deployment Options

Option 1: Deploy from GHCR (Registry) β€” Recommended

βœ… Best for: Most users, production deployments

# Pull pre-scanned image
docker pull ghcr.io/gsa-tts/hedgedoc:v1.0.0

# Deploy directly
docker run -p 3000:3000 ghcr.io/gsa-tts/hedgedoc:v1.0.0

# Or use cloud.gov manifest (pre-configured)
cf push hedgedoc

Advantages:

  • Pre-scanned and verified
  • No local build required
  • Reproducible: same image every time
  • SBOM and security reports available
  • Faster deployment

Option 2: Build Locally from Dockerfile

βœ… Best for: Development, customization, advanced compliance needs

# Clone and build
git clone https://github.com/GSA-TTS/collab-containers.git
cd collab-containers/hedgedoc

# Build with security checks
docker build -t hedgedoc:local .

# Scan before deployment
trivy image hedgedoc:local

# Deploy
docker run -it hedgedoc:local

Advantages:

  • Full control over build environment
  • Can customize Dockerfile
  • Review source code before building
  • Sign images locally with Cosign
  • Push to private registry

See DEPLOYMENT.md for detailed guides and examples.


Security & Compliance

Standards Alignment

  • βœ… NIST SP 800-53 β€” Security controls for federal systems
  • βœ… NIST SP 800-218 β€” Secure software development
  • βœ… OWASP Top 10 β€” Web application security
  • βœ… CIS Benchmarks β€” Container security hardening
  • βœ… SLSA Framework β€” Software supply chain security

Scanning Tools

  • Trivy β€” Container vulnerability and secret scanning
  • Gitleaks β€” Git history secret detection
  • Grype β€” Dependency vulnerability analysis
  • Hadolint β€” Dockerfile best practices linting

See SECURITY.md for vulnerability reporting and compliance details.


Centralized Scanning Service

This repo is set up for the GSA-TTS centralized scanning service.

  • renovate.json extends local>GSA-TTS/scanning-service:default.json5.
  • .github/workflows/dependency-lint.yml adds the org dependency lint PR check as a required gate.
  • .github/workflows/secret-scan.yml adds the org secret scan PR check as a required gate.
  • .githooks/pre-commit runs gitleaks detect --staged for local secret scanning.

Remaining manual onboarding steps

  1. Merge the Renovate onboarding PR if it has not already been merged for this repo.
  2. Review and merge the follow-up Renovate PR that pins mutable GitHub Action refs to full SHAs.
  3. Delete .github/dependabot.yml if it exists.
  4. In GitHub settings, disable Dependabot security updates but keep Dependabot alerts enabled.
  5. If this repo still has a repo-local vulnerability SLA workflow, delete it after confirming the centralized tracker is active.
  6. Optionally download the org .gitleaks.toml into the repo root if you want local gitleaks runs to use the shared org config.

Pre-commit hook setup

chmod +x .githooks/pre-commit
git config core.hooksPath .githooks

License

This project is licensed under the CC0 1.0 Universal (CC0 1.0) Public Domain Dedication. You can copy, modify, distribute, and perform the work, even for commercial purposes, all without asking permission. For more information, please visit CC0 1.0 Universal.

About

Containerized open-source collaboration tools for deployment on cloud.gov (GSA-TTS)

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages