_private/qwestly-docs/CI-CD/SOC2 Evidence Documentation.md

Table of Contents

CI/CD System Documentation for SOC2 Compliance

Qwestly, Inc.
Date: July 1, 2025
Document Version: 2.0

Executive Summary

Qwestly employs a hybrid CI/CD architecture that combines GitHub Actions for security validation and compliance with Vercel's native deployment platform. This approach ensures secure, reliable, and controlled software deployments while maintaining development velocity. Our system implements multiple layers of security controls, automated testing, and approval processes that align with SOC2 Trust Service Criteria.

System Architecture

Source Code Management

  • Platform: GitHub Enterprise
  • Repository Structure: Separate repositories for distinct applications
    • qwestly-app - Main application portal
    • candidate - Candidate-facing portal
    • public-site - Public marketing website
    • api-python - Python backend services
  • Branch Strategy: GitHub Flow with main as production branch
  • Access Control: Role-based access with mandatory 2FA

Hybrid CI/CD Architecture

GitHub Actions (Validation Layer)

Purpose: Security, compliance, and quality validation

  • Security scanning via Trivy vulnerability detection
  • Secret detection via TruffleHog credential scanning
  • Code quality validation via ESLint, TypeScript, and testing
  • Compliance artifact generation for SOC2 audit trail

Vercel Platform (Deployment Layer)

Purpose: Application building, deployment, and hosting

  • Automatic preview deployments on pull request creation
  • Production deployments triggered by main branch merges
  • Environment variable management via secure dashboard
  • Instant rollback capabilities via deployment history
  • Global CDN and edge optimization for performance

CI/CD Pipeline Components

1. Automated Security Scanning

  • Vulnerability Scanning: Trivy scanner for dependencies and containers
  • Secret Detection: TruffleHog for credential and API key detection
  • SARIF Integration: GitHub Security tab with artifact fallback
  • Permission Management: Proper security-events:write permissions configured

2. Quality Assurance Pipeline (Repository-Specific)

  • Code Linting: ESLint with Next.js configuration
  • Code Formatting: Prettier for consistent style
  • Type Safety: TypeScript compilation and type checking
  • Unit Testing: Vitest (qwestly-app) / Jest (candidate)
  • E2E Testing: Playwright with browser automation
  • Python Quality: Black, isort, mypy, pytest, bandit (api-python)

3. Deployment Controls

  • Environment Separation: Automatic staging via PR previews, controlled production deployment
  • Approval Gates: GitHub environment protection with required reviewers
  • Rollback Capability: One-click rollback via Vercel dashboard
  • Infrastructure as Code: Vercel configuration versioned with application code

Security Controls

Access Controls (CC6.1, CC6.2)

  • Multi-factor authentication required for all developers and administrators
  • Role-based access to repositories enforced through GitHub teams
  • Principle of least privilege applied to service accounts and deployment tokens
  • Quarterly access reviews conducted by security team
  • Session management with automatic timeout policies

Change Management (CC8.1)

  • Mandatory pull requests for all code changes to production branches
  • Peer review requirement with minimum one approval before merge
  • Branch protection rules preventing direct commits to main branch
  • Automated quality gates that must pass before deployment
  • Complete audit trail via Git commits and GitHub Actions logs
  • Deployment history tracked with user attribution and timestamps

Data Security (CC6.7)

  • Secrets management through GitHub Secrets and Vercel environment variables
  • No hardcoded credentials enforced via TruffleHog scanning
  • Encrypted communication for all CI/CD operations (HTTPS/TLS)
  • Secure artifact storage with configurable retention periods
  • Token scope limitation following principle of least privilege

Technical Implementation

GitHub Actions Workflow Architecture

Trigger (Push/PR) → Security Validation → Quality Checks → Compliance Validation
                                     ↓
                              Vercel Deployment (Automatic)
                                     ↓
                            Environment Protection (Production Only)

Repository-Specific Pipeline Configuration

qwestly-app (Main Application)

security-scan → lint-and-test → compliance-checks
                      ↓
              Vercel Preview/Production Deploy

candidate (Candidate Portal)

security-scan → compliance-checks (lint-and-test temporarily disabled)
                      ↓
              Vercel Preview/Production Deploy

api-python (Python Backend)

security-scan → python-quality-checks → compliance-checks  
                      ↓
              Vercel Preview/Production Deploy

Branch Protection Implementation

  • Pull request reviews required with minimum 1 approver
  • Status checks enforcement - all CI jobs must pass before merge
  • Up-to-date branch requirement ensures latest changes are tested
  • Administrator inclusion in restrictions (critical for SOC2)
  • Linear history enforcement for cleaner audit trails

Environment Protection Controls

  • Production environment requires explicit approval from designated reviewers
  • Staging environment allows automatic deployment for testing
  • Deployment branch restrictions limit production deploys to main branch only
  • Review dismissal on new commits ensures fresh approval for changes

Monitoring and Logging

Security Monitoring

  • Real-time vulnerability scanning on every commit and pull request
  • Security alert aggregation via GitHub Security tab and email notifications
  • Secret detection alerts with immediate notification to security team
  • SARIF report generation for compliance and audit evidence
  • Artifact retention ensuring scan results available for review periods

Deployment Monitoring

  • Build and deployment status tracked via Vercel dashboard
  • Performance monitoring with core web vitals and error tracking
  • Uptime monitoring with automated alerting for service disruptions
  • Deployment frequency metrics tracked for DORA performance indicators

Audit Trail Management

  • Complete Git history with signed commits for authenticity verification
  • CI/CD pipeline logs retained for minimum 1 year for compliance review
  • Deployment logs with user attribution and detailed operation history
  • Security scan archives stored as artifacts with configurable retention
  • Access log monitoring via GitHub audit log integration

Compliance Mapping

SOC2 Control Implementation Evidence Location Verification Method
CC6.1 - Logical Access GitHub 2FA + RBAC User management dashboard Quarterly access review
CC6.2 - Access Authorization Branch protection + env protection GitHub settings export Policy compliance scan
CC8.1 - Change Management PR approval + automated gates GitHub audit logs Sample deployment trace
CC6.7 - Data Transmission HTTPS/TLS + secret management Network security config Security scan reports
CC7.1 - System Monitoring Continuous security scanning GitHub Security tab Vulnerability trend analysis

Key Performance Indicators

Security Metrics

  • Vulnerability detection rate: 100% of commits scanned
  • Mean time to remediation: Target <24 hours for critical vulnerabilities
  • False positive rate: <5% for security scanning tools
  • Secret detection coverage: 100% of repository content scanned

Operational Metrics

  • Deployment frequency: Multiple times per day (staging), controlled for production
  • Lead time for changes: Average <2 hours from commit to production deployment
  • Mean time to recovery: <15 minutes via automated rollback capabilities
  • Change failure rate: <5% tracked over rolling 30-day periods

Compliance Metrics

  • PR approval compliance: 100% of production changes reviewed
  • Security scan pass rate: Target >95% initial scan success
  • Audit trail completeness: 100% of deployments logged with user attribution
  • Access review completion: 100% quarterly review completion rate

Supporting Evidence Documentation

1. Technical Configuration Evidence

  • GitHub repository settings export with branch protection configuration
  • GitHub Actions workflow definitions for all active repositories
  • Vercel deployment configuration including environment variables (non-sensitive)
  • Security scanning tool configuration with detection rule definitions

2. Operational Evidence

  • Sample CI/CD pipeline execution logs demonstrating complete workflow
  • Security scan reports showing vulnerability detection and remediation
  • Deployment audit trail with user attribution and approval workflow
  • Access control matrix documenting current team permissions and roles

3. Process Documentation

  • Incident response procedures for security vulnerabilities and deployment failures
  • Change management process including approval workflows and rollback procedures
  • Access management procedures including onboarding, role changes, and offboarding
  • Security review procedures for third-party dependencies and code changes

Risk Management and Controls

Identified Risks and Mitigations

  • Supply chain vulnerabilities: Mitigated via automated dependency scanning and update policies
  • Credential exposure: Prevented through secret scanning and secure credential management
  • Unauthorized access: Controlled via MFA, RBAC, and regular access reviews
  • Deployment failures: Minimized through automated testing and instant rollback capabilities
  • Data breaches: Prevented through encryption, access controls, and monitoring

Control Testing and Validation

  • Monthly penetration testing of deployed applications
  • Quarterly control testing of CI/CD pipeline security measures
  • Annual third-party security assessment of entire development and deployment process
  • Continuous vulnerability assessment via automated scanning and monitoring

Review and Maintenance

Regular Review Schedule

  • Weekly: Security scan result review and vulnerability remediation
  • Monthly: Pipeline performance optimization and metric analysis
  • Quarterly: Access control review and security control testing
  • Annually: Complete security assessment and control framework review

Change Management for CI/CD

  • All pipeline changes require pull request review and approval
  • Security tool updates require security team approval and testing
  • New repository setup follows standardized configuration checklist
  • Process improvements documented and communicated to all team members

Document Prepared By: Dominick Pham, CTO
Reviewed By: Adam Boender, CEO
Security Review By: [Security Team Lead]
Next Review Date: October 1, 2025
Document Classification: Internal Use - SOC2 Compliance