diff --git a/.codecov.yml b/.codecov.yml new file mode 100644 index 00000000..8aacb922 --- /dev/null +++ b/.codecov.yml @@ -0,0 +1,135 @@ +# ============================================================================= +# Codecov Configuration +# Require 75% overall coverage, exclude test files and non-source code +# ============================================================================= + +coverage: + status: + project: + default: + target: 85% + threshold: 0% + +# Fail CI if Codecov upload/report indicates a problem +require_ci_to_pass: yes + +# ----------------------------------------------------------------------------- +# Exclude from coverage reporting +# ----------------------------------------------------------------------------- +ignore: + # Test files + - "**/tests/**" + - "**/test/**" + - "**/__tests__/**" + - "**/test_*.go" + - "**/*_test.go" + - "**/*.test.ts" + - "**/*.test.tsx" + - "**/*.spec.ts" + - "**/*.spec.tsx" + - "**/vitest.config.ts" + - "**/vitest.setup.ts" + + # E2E tests + - "**/e2e/**" + - "**/integration/**" + + # Documentation + - "docs/**" + - "*.md" + + # CI/CD & Config + - ".github/**" + - "scripts/**" + - "tools/**" + - "*.yml" + - "*.yaml" + - "*.json" + + # Frontend build artifacts & dependencies + - "frontend/node_modules/**" + - "frontend/dist/**" + - "frontend/coverage/**" + - "frontend/test-results/**" + - "frontend/public/**" + + # Backend non-source files + - "backend/cmd/seed/**" + - "backend/data/**" + - "backend/coverage/**" + - "backend/bin/**" + - "backend/*.cover" + - "backend/*.out" + - "backend/*.html" + - "backend/codeql-db/**" + + # Docker-only code (not testable in CI) + - "backend/internal/services/docker_service.go" + - "backend/internal/api/handlers/docker_handler.go" + + # CodeQL artifacts + - "codeql-db/**" + - "codeql-db-*/**" + - "codeql-agent-results/**" + - "codeql-custom-queries-*/**" + - "*.sarif" + + # Config files (no logic) + - "**/tailwind.config.js" + - "**/postcss.config.js" + - "**/eslint.config.js" + - "**/vite.config.ts" + - "**/tsconfig*.json" + + # Type definitions only + - "**/*.d.ts" + + # Import/data directories + - "import/**" + - "data/**" + - ".cache/**" + + # CrowdSec config files (no logic to test) + - "configs/crowdsec/**" + + # ========================================================================== + # Backend packages excluded from coverage (match go-test-coverage.sh) + # These are entrypoints and infrastructure code that don't benefit from + # unit tests - they are tested via integration tests instead. + # ========================================================================== + + # Main entry points (bootstrap code only) + - "backend/cmd/api/**" + + # Infrastructure packages (logging, metrics, tracing) + # These are thin wrappers around external libraries with no business logic + - "backend/internal/logger/**" + - "backend/internal/metrics/**" + - "backend/internal/trace/**" + + # Backend test utilities (test infrastructure, not application code) + # These files contain testing helpers that take *testing.T and are only + # callable from *_test.go files - they cannot be covered by production code + - "backend/internal/api/handlers/testdb.go" + - "backend/internal/api/handlers/test_helpers.go" + + # DNS provider implementations (tested via integration tests, not unit tests) + # These are plugin implementations that interact with external DNS APIs + # and are validated through service-level integration tests + - "backend/pkg/dnsprovider/builtin/**" + + # ========================================================================== + # Frontend test utilities and helpers + # These are test infrastructure, not application code + # ========================================================================== + + # Test setup and utilities directory + - "frontend/src/test/**" + + # Vitest setup files + - "frontend/vitest.config.ts" + - "frontend/src/setupTests.ts" + + # Playwright E2E config + - "frontend/playwright.config.ts" + - "frontend/e2e/**" diff --git a/.docker/README.md b/.docker/README.md new file mode 100644 index 00000000..ae05f2d0 --- /dev/null +++ b/.docker/README.md @@ -0,0 +1,246 @@ +# Docker Deployment Guide + +Charon is designed for Docker-first deployment, making it easy for home users to run Caddy without learning Caddyfile syntax. + +## Directory Structure + +```text +.docker/ +├── compose/ # Docker Compose files +│ ├── docker-compose.yml # Main production compose +│ ├── docker-compose.dev.yml # Development overrides +│ ├── docker-compose.local.yml # Local development +│ ├── docker-compose.remote.yml # Remote deployment +│ └── docker-compose.override.yml # Personal overrides (gitignored) +├── docker-entrypoint.sh # Container entrypoint script +└── README.md # This file +``` + +## Quick Start + +```bash +# Clone the repository +git clone https://github.com/Wikid82/charon.git +cd charon + +# Start the stack (using new location) +docker compose -f .docker/compose/docker-compose.yml up -d + +# Access the UI +open http://localhost:8080 +``` + +## Usage + +When running docker-compose commands, specify the compose file location: + +```bash +# Production +docker compose -f .docker/compose/docker-compose.yml up -d + +# Development +docker compose -f .docker/compose/docker-compose.yml -f .docker/compose/docker-compose.dev.yml up -d + +# Local development +docker compose -f .docker/compose/docker-compose.local.yml up -d + +# With personal overrides +docker compose -f .docker/compose/docker-compose.yml -f .docker/compose/docker-compose.override.yml up -d +``` + +## Architecture + +Charon runs as a **single container** that includes: + +1. **Caddy Server**: The reverse proxy engine (ports 80/443). +2. **Charon Backend**: The Go API that manages Caddy via its API (binary: `charon`, `cpmp` symlink preserved). +3. **Charon Frontend**: The React web interface (port 8080). + +This unified architecture simplifies deployment, updates, and data management. + +```text +┌──────────────────────────────────────────┐ +│ Container (charon / cpmp) │ +│ │ +│ ┌──────────┐ API ┌──────────────┐ │ +│ │ Caddy │◄──:2019──┤ Charon App │ │ +│ │ (Proxy) │ │ (Manager) │ │ +│ └────┬─────┘ └──────┬───────┘ │ +│ │ │ │ +└───────┼───────────────────────┼──────────┘ + │ :80, :443 │ :8080 + ▼ ▼ + Internet Web UI +``` + +## Configuration + +### Volumes + +Persist your data by mounting these volumes: + +| Host Path | Container Path | Description | +|-----------|----------------|-------------| +| `./data` | `/app/data` | **Critical**. Stores the SQLite database (default `charon.db`, `cpm.db` fallback) and application logs. | +| `./caddy_data` | `/data` | **Critical**. Stores Caddy's SSL certificates and keys. | +| `./caddy_config` | `/config` | Stores Caddy's autosave configuration. | + +### Environment Variables + +Configure the application via `docker-compose.yml`: + +| Variable | Default | Description | +|----------|---------|-------------| +| `CHARON_ENV` | `production` | Set to `development` for verbose logging (`CPM_ENV` supported for backward compatibility). | +| `CHARON_HTTP_PORT` | `8080` | Port for the Web UI (`CPM_HTTP_PORT` supported for backward compatibility). | +| `CHARON_DB_PATH` | `/app/data/charon.db` | Path to the SQLite database (`CPM_DB_PATH` supported for backward compatibility). | +| `CHARON_CADDY_ADMIN_API` | `http://localhost:2019` | Internal URL for Caddy API (`CPM_CADDY_ADMIN_API` supported for backward compatibility). | + +## NAS Deployment Guides + +### Synology (Container Manager / Docker) + +1. **Prepare Folders**: Create a folder `docker/charon` (or `docker/cpmp` for backward compatibility) and subfolders `data`, `caddy_data`, and `caddy_config`. +2. **Download Image**: Search for `ghcr.io/wikid82/charon` in the Registry and download the `latest` tag. +3. **Launch Container**: + - **Network**: Use `Host` mode (recommended for Caddy to see real client IPs) OR bridge mode mapping ports `80:80`, `443:443`, and `8080:8080`. + - **Volume Settings**: + - `/docker/charon/data` -> `/app/data` (or `/docker/cpmp/data` -> `/app/data` for backward compatibility) + - `/docker/charon/caddy_data` -> `/data` (or `/docker/cpmp/caddy_data` -> `/data` for backward compatibility) + - `/docker/charon/caddy_config` -> `/config` (or `/docker/cpmp/caddy_config` -> `/config` for backward compatibility) + - **Environment**: Add `CHARON_ENV=production` (or `CPM_ENV=production` for backward compatibility). +4. **Finish**: Start the container and access `http://YOUR_NAS_IP:8080`. + +### Unraid + +1. **Community Apps**: (Coming Soon) Search for "charon". +2. **Manual Install**: + - Click **Add Container**. + - **Name**: Charon + - **Repository**: `ghcr.io/wikid82/charon:latest` + - **Network Type**: Bridge + - **WebUI**: `http://[IP]:[PORT:8080]` + - **Port mappings**: + - Container Port: `80` -> Host Port: `80` + - Container Port: `443` -> Host Port: `443` + - Container Port: `8080` -> Host Port: `8080` + - **Paths**: + - `/mnt/user/appdata/charon/data` -> `/app/data` (or `/mnt/user/appdata/cpmp/data` -> `/app/data` for backward compatibility) + - `/mnt/user/appdata/charon/caddy_data` -> `/data` (or `/mnt/user/appdata/cpmp/caddy_data` -> `/data` for backward compatibility) + - `/mnt/user/appdata/charon/caddy_config` -> `/config` (or `/mnt/user/appdata/cpmp/caddy_config` -> `/config` for backward compatibility) +3. **Apply**: Click Done to pull and start. + +## Troubleshooting + +### App can't reach Caddy + +**Symptom**: "Caddy unreachable" errors in logs + +**Solution**: Since both run in the same container, this usually means Caddy failed to start. Check logs: + +```bash +docker compose -f .docker/compose/docker-compose.yml logs app +``` + +### Certificates not working + +**Symptom**: HTTP works but HTTPS fails + +**Check**: + +1. Port 80/443 are accessible from the internet +2. DNS points to your server +3. Caddy logs: `docker compose -f .docker/compose/docker-compose.yml logs app | grep -i acme` + +### Config changes not applied + +**Symptom**: Changes in UI don't affect routing + +**Debug**: + +```bash +# View current Caddy config +curl http://localhost:2019/config/ | jq + +# Check Charon logs +docker compose -f .docker/compose/docker-compose.yml logs app + +# Manual config reload +curl -X POST http://localhost:8080/api/v1/caddy/reload +``` + +## Updating + +Pull the latest images and restart: + +```bash +docker compose -f .docker/compose/docker-compose.yml pull +docker compose -f .docker/compose/docker-compose.yml up -d +``` + +For specific versions: + +```bash +# Edit docker-compose.yml to pin version +image: ghcr.io/wikid82/charon:v1.0.0 + +docker compose -f .docker/compose/docker-compose.yml up -d +``` + +## Building from Source + +```bash +# Build multi-arch images +docker buildx build --platform linux/amd64,linux/arm64 -t charon:local . + +# Or use Make +make docker-build +``` + +## Security Considerations + +1. **Caddy admin API**: Keep port 2019 internal (not exposed in production compose) +2. **Management UI**: Add authentication (Issue #7) before exposing to internet +3. **Certificates**: Caddy stores private keys in `caddy_data` - protect this volume +4. **Database**: SQLite file contains all config - backup regularly + +## Integration with Existing Caddy + +If you already have Caddy running, you can point Charon to it: + +```yaml +environment: + - CPM_CADDY_ADMIN_API=http://your-caddy-host:2019 +``` + +**Warning**: Charon will replace Caddy's entire configuration. Backup first! + +## Performance Tuning + +For high-traffic deployments: + +```yaml +# docker-compose.yml +services: + app: + deploy: + resources: + limits: + memory: 512M + reservations: + memory: 256M +``` + +## Important Notes + +- **Override Location Change**: The `docker-compose.override.yml` file has moved from + the project root to `.docker/compose/`. Update your local workflows accordingly. +- Personal override files (`.docker/compose/docker-compose.override.yml`) are gitignored + and should contain machine-specific configurations only. + +## Next Steps + +- Configure your first proxy host via UI +- Enable automatic HTTPS (happens automatically) +- Add authentication (Issue #7) +- Integrate CrowdSec (Issue #15) diff --git a/.docker/compose/README.md b/.docker/compose/README.md new file mode 100644 index 00000000..fcb7a990 --- /dev/null +++ b/.docker/compose/README.md @@ -0,0 +1,50 @@ +# Docker Compose Files + +This directory contains all Docker Compose configuration variants for Charon. + +## File Descriptions + +| File | Purpose | +|------|---------| +| `docker-compose.yml` | Main production compose configuration. Base services and production settings. | +| `docker-compose.dev.yml` | Development overrides. Enables hot-reload, debug logging, and development tools. | +| `docker-compose.local.yml` | Local development configuration. Standalone setup for local testing. | +| `docker-compose.remote.yml` | Remote deployment configuration. Settings for deploying to remote servers. | +| `docker-compose.override.yml` | Personal local overrides. **Gitignored** - use for machine-specific settings. | + +## Usage Patterns + +### Production Deployment + +```bash +docker compose -f .docker/compose/docker-compose.yml up -d +``` + +### Development Mode + +```bash +docker compose -f .docker/compose/docker-compose.yml \ + -f .docker/compose/docker-compose.dev.yml up -d +``` + +### Local Testing + +```bash +docker compose -f .docker/compose/docker-compose.local.yml up -d +``` + +### With Personal Overrides + +Create your own `docker-compose.override.yml` in this directory for personal +configurations (port mappings, volume paths, etc.). This file is gitignored. + +```bash +docker compose -f .docker/compose/docker-compose.yml \ + -f .docker/compose/docker-compose.override.yml up -d +``` + +## Notes + +- Always use the `-f` flag to specify compose file paths from the project root +- The override file is automatically ignored by git - do not commit personal settings +- See project tasks in VS Code for convenient pre-configured commands diff --git a/.docker/compose/docker-compose.dev.yml b/.docker/compose/docker-compose.dev.yml new file mode 100644 index 00000000..7c4a8261 --- /dev/null +++ b/.docker/compose/docker-compose.dev.yml @@ -0,0 +1,42 @@ +# Development override - use with: docker-compose -f docker-compose.yml -f docker-compose.dev.yml up + +services: + app: + image: ghcr.io/wikid82/charon:dev + # Development: expose Caddy admin API externally for debugging + ports: + - "80:80" + - "443:443" + - "443:443/udp" + - "8080:8080" + - "2019:2019" # Caddy admin API (dev only) + environment: + - CHARON_ENV=development + - CPM_ENV=development + - CHARON_HTTP_PORT=8080 + - CPM_HTTP_PORT=80 + # Generate with: openssl rand -base64 32 + - CHARON_ENCRYPTION_KEY=your-32-byte-base64-key-here + - CHARON_DB_PATH=/app/data/charon.db + - CHARON_FRONTEND_DIR=/app/frontend/dist + - CHARON_CADDY_ADMIN_API=http://localhost:2019 + - CHARON_CADDY_CONFIG_DIR=/app/data/caddy + # Security Services (Optional) + # 🚨 DEPRECATED: Use GUI toggle in Security dashboard instead + #- CPM_SECURITY_CROWDSEC_MODE=disabled # ⚠️ DEPRECATED + #- CPM_SECURITY_CROWDSEC_API_URL= # ⚠️ DEPRECATED + #- CPM_SECURITY_CROWDSEC_API_KEY= # ⚠️ DEPRECATED + #- CPM_SECURITY_WAF_MODE=disabled + #- CPM_SECURITY_RATELIMIT_ENABLED=false + #- CPM_SECURITY_ACL_ENABLED=false + - FEATURE_CERBERUS_ENABLED=true + volumes: + - /var/run/docker.sock:/var/run/docker.sock:ro # For local container discovery + - crowdsec_data:/app/data/crowdsec + # Mount your existing Caddyfile for automatic import (optional) + # - ./my-existing-Caddyfile:/import/Caddyfile:ro + # - ./sites:/import/sites:ro # If your Caddyfile imports other files + +volumes: + crowdsec_data: + driver: local diff --git a/.docker/compose/docker-compose.e2e.cerberus-disabled.override.yml b/.docker/compose/docker-compose.e2e.cerberus-disabled.override.yml new file mode 100644 index 00000000..839045b3 --- /dev/null +++ b/.docker/compose/docker-compose.e2e.cerberus-disabled.override.yml @@ -0,0 +1,4 @@ +services: + charon-e2e: + environment: + - CHARON_SECURITY_CERBERUS_ENABLED=false diff --git a/.docker/compose/docker-compose.e2e.yml b/.docker/compose/docker-compose.e2e.yml new file mode 100644 index 00000000..6f536981 --- /dev/null +++ b/.docker/compose/docker-compose.e2e.yml @@ -0,0 +1,52 @@ +# Docker Compose for E2E Testing +# +# This configuration runs Charon with a fresh, isolated database specifically for +# Playwright E2E tests. Use this to ensure tests start with a clean state. +# +# Usage: +# docker compose -f .docker/compose/docker-compose.e2e.yml up -d +# +# The setup API will be available since no users exist in the fresh database. +# The auth.setup.ts fixture will create a test admin user automatically. + +services: + charon-e2e: + image: charon:local + container_name: charon-e2e + restart: "no" + ports: + - "8080:8080" # Management UI (Charon) + - "2020:2020" # Emergency server (DO NOT expose publicly in production!) + environment: + - CHARON_ENV=e2e # Enable lenient rate limiting (50 attempts/min) for E2E tests + - CHARON_DEBUG=0 + - TZ=UTC + # Encryption key - MUST be provided via environment variable + # Generate with: export CHARON_ENCRYPTION_KEY=$(openssl rand -base64 32) + - CHARON_ENCRYPTION_KEY=${CHARON_ENCRYPTION_KEY:?CHARON_ENCRYPTION_KEY is required} + # Emergency reset token - for break-glass recovery when locked out by ACL + # Generate with: openssl rand -hex 32 + - CHARON_EMERGENCY_TOKEN=${CHARON_EMERGENCY_TOKEN:-test-emergency-token-for-e2e-32chars} + # Emergency server (Tier 2 break glass) - separate port bypassing all security + - CHARON_EMERGENCY_SERVER_ENABLED=true + - CHARON_EMERGENCY_BIND=0.0.0.0:2020 # Bind to all interfaces in container (avoid Caddy's 2019) + - CHARON_EMERGENCY_USERNAME=admin + - CHARON_EMERGENCY_PASSWORD=${CHARON_EMERGENCY_PASSWORD:-changeme} + - CHARON_HTTP_PORT=8080 + - CHARON_DB_PATH=/app/data/charon.db + - CHARON_FRONTEND_DIR=/app/frontend/dist + - CHARON_CADDY_ADMIN_API=http://localhost:2019 + - CHARON_CADDY_CONFIG_DIR=/app/data/caddy + - CHARON_CADDY_BINARY=caddy + - CHARON_ACME_STAGING=true + # FEATURE_CERBERUS_ENABLED deprecated - Cerberus enabled by default + tmpfs: + # True tmpfs for E2E test data - fresh on every run, in-memory only + # mode=1777 allows any user to write (container runs as non-root) + - /app/data:size=100M,mode=1777 + healthcheck: + test: ["CMD-SHELL", "curl -fsS http://localhost:8080/api/v1/health || exit 1"] + interval: 5s + timeout: 5s + retries: 10 + start_period: 10s diff --git a/.docker/compose/docker-compose.local.yml b/.docker/compose/docker-compose.local.yml new file mode 100644 index 00000000..af941ce2 --- /dev/null +++ b/.docker/compose/docker-compose.local.yml @@ -0,0 +1,64 @@ +services: + charon: + image: charon:local + container_name: charon + restart: unless-stopped + ports: + - "80:80" # HTTP (Caddy proxy) + - "443:443" # HTTPS (Caddy proxy) + - "443:443/udp" # HTTP/3 (Caddy proxy) + - "8080:8080" # Management UI (Charon) + - "2345:2345" # Delve Debugger + environment: + - CHARON_ENV=development + - CHARON_DEBUG=1 + - TZ=America/New_York + # Generate with: openssl rand -base64 32 + - CHARON_ENCRYPTION_KEY=your-32-byte-base64-key-here + - CHARON_HTTP_PORT=8080 + - CHARON_DB_PATH=/app/data/charon.db + - CHARON_FRONTEND_DIR=/app/frontend/dist + - CHARON_CADDY_ADMIN_API=http://localhost:2019 + - CHARON_CADDY_CONFIG_DIR=/app/data/caddy + - CHARON_CADDY_BINARY=caddy + - CHARON_IMPORT_CADDYFILE=/import/Caddyfile + - CHARON_IMPORT_DIR=/app/data/imports + - CHARON_ACME_STAGING=false + - FEATURE_CERBERUS_ENABLED=true + # Emergency "break-glass" token for security reset when ACL blocks access + - CHARON_EMERGENCY_TOKEN=03e4682c1164f0c1cb8e17c99bd1a2d9156b59824dde41af3bb67c513e5c5e92 + extra_hosts: + - "host.docker.internal:host-gateway" + cap_add: + - SYS_PTRACE + security_opt: + - seccomp:unconfined + volumes: + - charon_data:/app/data + - caddy_data:/data + - caddy_config:/config + - crowdsec_data:/app/data/crowdsec + - plugins_data:/app/plugins # Read-write for development/hot-loading + - /var/run/docker.sock:/var/run/docker.sock:ro # For local container discovery + - ./backend:/app/backend:ro # Mount source for debugging + # Mount your existing Caddyfile for automatic import (optional) +# - :/import/Caddyfile:ro +# - :/import/sites:ro # If your Caddyfile imports other files + healthcheck: + test: ["CMD-SHELL", "curl -fsS http://localhost:8080/api/v1/health || exit 1"] + interval: 30s + timeout: 10s + retries: 3 + start_period: 40s + +volumes: + charon_data: + driver: local + caddy_data: + driver: local + caddy_config: + driver: local + crowdsec_data: + driver: local + plugins_data: + driver: local diff --git a/.docker/compose/docker-compose.playwright.yml b/.docker/compose/docker-compose.playwright.yml new file mode 100644 index 00000000..73ad8ea2 --- /dev/null +++ b/.docker/compose/docker-compose.playwright.yml @@ -0,0 +1,139 @@ +# Playwright E2E Test Environment +# ================================ +# This configuration is specifically designed for Playwright E2E testing, +# both for local development and CI/CD pipelines. +# +# Usage: +# # Start basic E2E environment +# docker compose -f .docker/compose/docker-compose.playwright.yml up -d +# +# # Start with security testing services (CrowdSec) +# docker compose -f .docker/compose/docker-compose.playwright.yml --profile security-tests up -d +# +# # Start with notification testing services (MailHog) +# docker compose -f .docker/compose/docker-compose.playwright.yml --profile notification-tests up -d +# +# # Start with all optional services +# docker compose -f .docker/compose/docker-compose.playwright.yml --profile security-tests --profile notification-tests up -d +# +# The setup API will be available since no users exist in the fresh database. +# The auth.setup.ts fixture will create a test admin user automatically. + +services: + # ============================================================================= + # Charon Application - Core E2E Testing Service + # ============================================================================= + charon-app: + build: + context: ../.. + dockerfile: Dockerfile + container_name: charon-playwright + restart: "no" + ports: + - "8080:8080" # Management UI (Charon) + environment: + # Core configuration + - CHARON_ENV=test + - CHARON_DEBUG=0 + - TZ=UTC + # E2E testing encryption key - 32 bytes base64 encoded (not for production!) + # Encryption key - MUST be provided via environment variable + # Generate with: export CHARON_ENCRYPTION_KEY=$(openssl rand -base64 32) + - CHARON_ENCRYPTION_KEY=${CHARON_ENCRYPTION_KEY:?CHARON_ENCRYPTION_KEY is required} + # Emergency reset token - for break-glass recovery when locked out by ACL + # Generate with: openssl rand -hex 32 + - CHARON_EMERGENCY_TOKEN=${CHARON_EMERGENCY_TOKEN:-test-emergency-token-for-e2e-32chars} + # Server settings + - CHARON_HTTP_PORT=8080 + - CHARON_DB_PATH=/app/data/charon.db + - CHARON_FRONTEND_DIR=/app/frontend/dist + # Caddy settings + - CHARON_CADDY_ADMIN_API=http://localhost:2019 + - CHARON_CADDY_CONFIG_DIR=/app/data/caddy + - CHARON_CADDY_BINARY=caddy + # ACME settings (staging for E2E tests) + - CHARON_ACME_STAGING=true + # Security features - disabled by default for faster tests + # Enable via profile: --profile security-tests + # FEATURE_CERBERUS_ENABLED deprecated - Cerberus enabled by default + - CHARON_SECURITY_CROWDSEC_MODE=disabled + # SMTP for notification tests (connects to MailHog when profile enabled) + - CHARON_SMTP_HOST=mailhog + - CHARON_SMTP_PORT=1025 + - CHARON_SMTP_AUTH=false + volumes: + # Named volume for test data persistence during test runs + - playwright_data:/app/data + - playwright_caddy_data:/data + - playwright_caddy_config:/config + healthcheck: + test: ["CMD", "curl", "-sf", "http://localhost:8080/api/v1/health"] + interval: 5s + timeout: 3s + retries: 12 + start_period: 10s + networks: + - playwright-network + + # ============================================================================= + # CrowdSec - Security Testing Service (Optional Profile) + # ============================================================================= + crowdsec: + image: crowdsecurity/crowdsec:latest + container_name: charon-playwright-crowdsec + profiles: + - security-tests + restart: "no" + environment: + - COLLECTIONS=crowdsecurity/nginx crowdsecurity/http-cve + - BOUNCER_KEY_charon=test-bouncer-key-for-e2e + # Disable online features for isolated testing + - DISABLE_ONLINE_API=true + volumes: + - playwright_crowdsec_data:/var/lib/crowdsec/data + - playwright_crowdsec_config:/etc/crowdsec + healthcheck: + test: ["CMD", "cscli", "version"] + interval: 10s + timeout: 5s + retries: 5 + start_period: 30s + networks: + - playwright-network + + # ============================================================================= + # MailHog - Email Testing Service (Optional Profile) + # ============================================================================= + mailhog: + image: mailhog/mailhog:latest + container_name: charon-playwright-mailhog + profiles: + - notification-tests + restart: "no" + ports: + - "1025:1025" # SMTP server + - "8025:8025" # Web UI for viewing emails + networks: + - playwright-network + +# ============================================================================= +# Named Volumes +# ============================================================================= +volumes: + playwright_data: + driver: local + playwright_caddy_data: + driver: local + playwright_caddy_config: + driver: local + playwright_crowdsec_data: + driver: local + playwright_crowdsec_config: + driver: local + +# ============================================================================= +# Networks +# ============================================================================= +networks: + playwright-network: + driver: bridge diff --git a/.docker/compose/docker-compose.remote.yml b/.docker/compose/docker-compose.remote.yml new file mode 100644 index 00000000..0ab6f481 --- /dev/null +++ b/.docker/compose/docker-compose.remote.yml @@ -0,0 +1,19 @@ +version: '3.9' + +services: + # Run this service on your REMOTE servers (not the one running Charon) + # to allow Charon to discover containers running there (legacy: CPMP). + docker-socket-proxy: + image: alpine/socat + container_name: docker-socket-proxy + restart: unless-stopped + ports: + # Expose port 2375. + # ⚠️ SECURITY WARNING: Ensure this port is NOT accessible from the public internet! + # Use a VPN (Tailscale, WireGuard) or a private local network (LAN). + - "2375:2375" + volumes: + # Give the proxy access to the host's Docker socket + - /var/run/docker.sock:/var/run/docker.sock:ro + # Forward TCP traffic from port 2375 to the internal Docker socket + command: tcp-listen:2375,fork,reuseaddr unix-connect:/var/run/docker.sock diff --git a/.docker/compose/docker-compose.yml b/.docker/compose/docker-compose.yml new file mode 100644 index 00000000..34a66e24 --- /dev/null +++ b/.docker/compose/docker-compose.yml @@ -0,0 +1,84 @@ +services: + charon: + image: ghcr.io/wikid82/charon:latest + container_name: charon + restart: unless-stopped + ports: + - "80:80" # HTTP (Caddy proxy) + - "443:443" # HTTPS (Caddy proxy) + - "443:443/udp" # HTTP/3 (Caddy proxy) + - "8080:8080" # Management UI (Charon) + # Emergency server port - ONLY expose via SSH tunnel or VPN for security + # Uncomment ONLY if you need localhost access on host machine: + # - "127.0.0.1:2019:2019" # Emergency server (localhost-only) + environment: + - CHARON_ENV=production # CHARON_ preferred; CPM_ values still supported + - TZ=UTC # Set timezone (e.g., America/New_York) + # Generate with: openssl rand -base64 32 + - CHARON_ENCRYPTION_KEY=your-32-byte-base64-key-here + # Emergency break glass configuration (Tier 1 & Tier 2) + # Tier 1: Emergency token for Layer 7 bypass within application + # Generate with: openssl rand -hex 32 + # - CHARON_EMERGENCY_TOKEN=${CHARON_EMERGENCY_TOKEN} # Store in secrets manager + # Tier 2: Emergency server on separate port (bypasses Caddy/CrowdSec entirely) + # - CHARON_EMERGENCY_SERVER_ENABLED=false # Disabled by default + # - CHARON_EMERGENCY_BIND=127.0.0.1:2019 # Localhost only + # - CHARON_EMERGENCY_USERNAME=admin + # - CHARON_EMERGENCY_PASSWORD=${EMERGENCY_PASSWORD} # Store in secrets manager + - CHARON_HTTP_PORT=8080 + - CHARON_DB_PATH=/app/data/charon.db + - CHARON_FRONTEND_DIR=/app/frontend/dist + - CHARON_CADDY_ADMIN_API=http://localhost:2019 + - CHARON_CADDY_CONFIG_DIR=/app/data/caddy + - CHARON_CADDY_BINARY=caddy + - CHARON_IMPORT_CADDYFILE=/import/Caddyfile + - CHARON_IMPORT_DIR=/app/data/imports + # Security Services (Optional) + # 🚨 DEPRECATED: CrowdSec environment variables are no longer used. + # CrowdSec is now GUI-controlled via the Security dashboard. + # Remove these lines and use the GUI toggle instead. + # See: https://wikid82.github.io/charon/migration-guide + #- CERBERUS_SECURITY_CROWDSEC_MODE=disabled # ⚠️ DEPRECATED - Use GUI toggle + #- CERBERUS_SECURITY_CROWDSEC_API_URL= # ⚠️ DEPRECATED - External mode removed + #- CERBERUS_SECURITY_CROWDSEC_API_KEY= # ⚠️ DEPRECATED - External mode removed + #- CERBERUS_SECURITY_WAF_MODE=disabled # disabled, enabled + #- CERBERUS_SECURITY_RATELIMIT_ENABLED=false + #- CERBERUS_SECURITY_ACL_ENABLED=false + # Backward compatibility: CPM_ prefixed variables are still supported + # 🚨 DEPRECATED: Use GUI toggle instead (see Security dashboard) + #- CPM_SECURITY_CROWDSEC_MODE=disabled # ⚠️ DEPRECATED + #- CPM_SECURITY_CROWDSEC_API_URL= # ⚠️ DEPRECATED + #- CPM_SECURITY_CROWDSEC_API_KEY= # ⚠️ DEPRECATED + #- CPM_SECURITY_WAF_MODE=disabled + #- CPM_SECURITY_RATELIMIT_ENABLED=false + #- CPM_SECURITY_ACL_ENABLED=false + extra_hosts: + - "host.docker.internal:host-gateway" + volumes: + - cpm_data:/app/data # existing data (legacy name); charon will also use this path by default for backward compatibility + - caddy_data:/data + - caddy_config:/config + - crowdsec_data:/app/data/crowdsec + - plugins_data:/app/plugins:ro # Read-only in production for security + - /var/run/docker.sock:/var/run/docker.sock:ro # For local container discovery + # Mount your existing Caddyfile for automatic import (optional) + # - ./my-existing-Caddyfile:/import/Caddyfile:ro + # - ./sites:/import/sites:ro # If your Caddyfile imports other files + healthcheck: + test: ["CMD-SHELL", "curl -fsS http://localhost:8080/api/v1/health || exit 1"] + interval: 30s + timeout: 10s + retries: 3 + start_period: 40s + +volumes: + cpm_data: + driver: local + caddy_data: + driver: local + caddy_config: + driver: local + crowdsec_data: + driver: local + plugins_data: + driver: local diff --git a/.docker/docker-entrypoint.sh b/.docker/docker-entrypoint.sh new file mode 100755 index 00000000..58ce312c --- /dev/null +++ b/.docker/docker-entrypoint.sh @@ -0,0 +1,353 @@ +#!/bin/sh +set -e + +# Entrypoint script to run both Caddy and Charon in a single container +# This simplifies deployment for home users + +echo "Starting Charon with integrated Caddy..." + +is_root() { + [ "$(id -u)" -eq 0 ] +} + +run_as_charon() { + if is_root; then + gosu charon "$@" + else + "$@" + fi +} + +# ============================================================================ +# Volume Permission Handling for Non-Root User +# ============================================================================ +# When running as non-root user (charon), mounted volumes may have incorrect +# permissions. This section ensures the application can write to required paths. +# Note: This runs as the charon user, so we can only fix owned directories. + +# Ensure /app/data exists and is writable (primary data volume) +if [ ! -w "/app/data" ] 2>/dev/null; then + echo "Warning: /app/data is not writable. Please ensure volume permissions are correct." + echo " Run: docker run ... -v charon_data:/app/data ..." + echo " Or fix permissions: chown -R 1000:1000 /path/to/volume" +fi + +# Ensure /config exists and is writable (Caddy config volume) +if [ ! -w "/config" ] 2>/dev/null; then + echo "Warning: /config is not writable. Please ensure volume permissions are correct." +fi + +# Create required subdirectories in writable volumes +mkdir -p /app/data/caddy 2>/dev/null || true +mkdir -p /app/data/crowdsec 2>/dev/null || true +mkdir -p /app/data/geoip 2>/dev/null || true + +# Fix ownership for directories created as root +if is_root; then + chown -R charon:charon /app/data/caddy 2>/dev/null || true + chown -R charon:charon /app/data/crowdsec 2>/dev/null || true + chown -R charon:charon /app/data/geoip 2>/dev/null || true +fi + +# ============================================================================ +# Plugin Directory Permission Verification +# ============================================================================ +# The PluginLoaderService requires the plugin directory to NOT be world-writable +# (mode 0002 bit must not be set). This is a security requirement to prevent +# malicious plugin injection. +PLUGINS_DIR="${CHARON_PLUGINS_DIR:-/app/plugins}" +if [ -d "$PLUGINS_DIR" ]; then + # Check if directory is world-writable (security risk) + # Using find -perm -0002 is more robust than stat regex - handles sticky/setgid bits correctly + if find "$PLUGINS_DIR" -maxdepth 0 -perm -0002 -print -quit 2>/dev/null | grep -q .; then + echo "⚠️ WARNING: Plugin directory $PLUGINS_DIR is world-writable!" + echo " This is a security risk - plugins could be injected by any user." + echo " Attempting to fix permissions (removing world-writable bit)..." + # Use chmod o-w to only remove world-writable, preserving sticky/setgid bits + if chmod o-w "$PLUGINS_DIR" 2>/dev/null; then + echo " ✓ Fixed: Plugin directory world-writable permission removed" + else + echo " ✗ ERROR: Cannot fix permissions. Please run: chmod o-w $PLUGINS_DIR" + echo " Plugin loading may fail due to insecure permissions." + fi + else + echo "✓ Plugin directory permissions OK: $PLUGINS_DIR" + fi +else + echo "Note: Plugin directory $PLUGINS_DIR does not exist (plugins disabled)" +fi + +# ============================================================================ +# Docker Socket Permission Handling +# ============================================================================ +# The Docker integration feature requires access to the Docker socket. +# If the container runs as root, we can auto-align group membership with the +# socket GID. If running non-root (default), we cannot modify groups; users +# can enable Docker integration by using a compatible GID / --group-add. + +if [ -S "/var/run/docker.sock" ] && is_root; then + DOCKER_SOCK_GID=$(stat -c '%g' /var/run/docker.sock 2>/dev/null || echo "") + if [ -n "$DOCKER_SOCK_GID" ] && [ "$DOCKER_SOCK_GID" != "0" ]; then + # Check if a group with this GID exists + if ! getent group "$DOCKER_SOCK_GID" >/dev/null 2>&1; then + echo "Docker socket detected (gid=$DOCKER_SOCK_GID) - creating docker group and adding charon user..." + # Create docker group with the socket's GID + groupadd -g "$DOCKER_SOCK_GID" docker 2>/dev/null || true + # Add charon user to the docker group + usermod -aG docker charon 2>/dev/null || true + echo "Docker integration enabled for charon user" + else + # Group exists, just add charon to it + GROUP_NAME=$(getent group "$DOCKER_SOCK_GID" | cut -d: -f1) + echo "Docker socket detected (gid=$DOCKER_SOCK_GID, group=$GROUP_NAME) - adding charon user..." + usermod -aG "$GROUP_NAME" charon 2>/dev/null || true + echo "Docker integration enabled for charon user" + fi + fi +elif [ -S "/var/run/docker.sock" ]; then + echo "Note: Docker socket mounted but container is running non-root; skipping docker.sock group setup." + echo " If Docker discovery is needed, run with matching group permissions (e.g., --group-add)" +else + echo "Note: Docker socket not found. Docker container discovery will be unavailable." +fi + +# ============================================================================ +# CrowdSec Initialization +# ============================================================================ +# Note: CrowdSec agent is not auto-started. Lifecycle is GUI-controlled via backend handlers. + +# Initialize CrowdSec configuration if cscli is present +if command -v cscli >/dev/null; then + echo "Initializing CrowdSec configuration..." + + # Define persistent paths + CS_PERSIST_DIR="/app/data/crowdsec" + CS_CONFIG_DIR="$CS_PERSIST_DIR/config" + CS_DATA_DIR="$CS_PERSIST_DIR/data" + CS_LOG_DIR="/var/log/crowdsec" + + # Ensure persistent directories exist (within writable volume) + mkdir -p "$CS_CONFIG_DIR" 2>/dev/null || echo "Warning: Cannot create $CS_CONFIG_DIR" + mkdir -p "$CS_DATA_DIR" 2>/dev/null || echo "Warning: Cannot create $CS_DATA_DIR" + mkdir -p "$CS_PERSIST_DIR/hub_cache" + # Log directories are created at build time with correct ownership + # Only attempt to create if they don't exist (first run scenarios) + mkdir -p /var/log/crowdsec 2>/dev/null || true + mkdir -p /var/log/caddy 2>/dev/null || true + + # Initialize persistent config if key files are missing + if [ ! -f "$CS_CONFIG_DIR/config.yaml" ]; then + echo "Initializing persistent CrowdSec configuration..." + if [ -d "/etc/crowdsec.dist" ] && [ -n "$(ls -A /etc/crowdsec.dist 2>/dev/null)" ]; then + cp -r /etc/crowdsec.dist/* "$CS_CONFIG_DIR/" || { + echo "ERROR: Failed to copy config from /etc/crowdsec.dist" + exit 1 + } + echo "Successfully initialized config from .dist directory" + elif [ -d "/etc/crowdsec" ] && [ ! -L "/etc/crowdsec" ] && [ -n "$(ls -A /etc/crowdsec 2>/dev/null)" ]; then + cp -r /etc/crowdsec/* "$CS_CONFIG_DIR/" || { + echo "ERROR: Failed to copy config from /etc/crowdsec" + exit 1 + } + echo "Successfully initialized config from /etc/crowdsec" + else + echo "ERROR: No config source found (neither .dist nor /etc/crowdsec available)" + exit 1 + fi + fi + + # Verify symlink exists (created at build time) + # Note: Symlink is created in Dockerfile as root before switching to non-root user + # Non-root users cannot create symlinks in /etc, so this must be done at build time + if [ -L "/etc/crowdsec" ]; then + echo "CrowdSec config symlink verified: /etc/crowdsec -> $CS_CONFIG_DIR" + else + echo "WARNING: /etc/crowdsec symlink not found. This may indicate a build issue." + echo "Expected: /etc/crowdsec -> /app/data/crowdsec/config" + # Try to continue anyway - config may still work if CrowdSec uses CFG env var + fi + + # Create/update acquisition config for Caddy logs + if [ ! -f "/etc/crowdsec/acquis.yaml" ] || [ ! -s "/etc/crowdsec/acquis.yaml" ]; then + echo "Creating acquisition configuration for Caddy logs..." + cat > /etc/crowdsec/acquis.yaml << 'ACQUIS_EOF' +# Caddy access logs acquisition +# CrowdSec will monitor these files for security events +source: file +filenames: + - /var/log/caddy/access.log + - /var/log/caddy/*.log +labels: + type: caddy +ACQUIS_EOF + fi + + # Ensure hub directory exists in persistent storage + mkdir -p /etc/crowdsec/hub + + # Perform variable substitution + export CFG=/etc/crowdsec + export DATA="$CS_DATA_DIR" + export PID=/var/run/crowdsec.pid + export LOG="$CS_LOG_DIR/crowdsec.log" + + # Process config.yaml and user.yaml with envsubst + # We use a temp file to avoid issues with reading/writing same file + for file in /etc/crowdsec/config.yaml /etc/crowdsec/user.yaml; do + if [ -f "$file" ]; then + envsubst < "$file" > "$file.tmp" && mv "$file.tmp" "$file" + chown charon:charon "$file" 2>/dev/null || true + fi + done + + # Configure CrowdSec LAPI to use port 8085 to avoid conflict with Charon (port 8080) + if [ -f "/etc/crowdsec/config.yaml" ]; then + sed -i 's|listen_uri: 127.0.0.1:8080|listen_uri: 127.0.0.1:8085|g' /etc/crowdsec/config.yaml + sed -i 's|listen_uri: 0.0.0.0:8080|listen_uri: 127.0.0.1:8085|g' /etc/crowdsec/config.yaml + fi + + # Update local_api_credentials.yaml to use correct port + if [ -f "/etc/crowdsec/local_api_credentials.yaml" ]; then + sed -i 's|url: http://127.0.0.1:8080|url: http://127.0.0.1:8085|g' /etc/crowdsec/local_api_credentials.yaml + sed -i 's|url: http://localhost:8080|url: http://127.0.0.1:8085|g' /etc/crowdsec/local_api_credentials.yaml + fi + + # Fix log directory path (ensure it points to /var/log/crowdsec/ not /var/log/) + sed -i 's|log_dir: /var/log/$|log_dir: /var/log/crowdsec/|g' "$CS_CONFIG_DIR/config.yaml" + # Also handle case where it might be without trailing slash + sed -i 's|log_dir: /var/log$|log_dir: /var/log/crowdsec|g' "$CS_CONFIG_DIR/config.yaml" + + # Verify LAPI configuration was applied correctly + if grep -q "listen_uri:.*:8085" "$CS_CONFIG_DIR/config.yaml"; then + echo "✓ CrowdSec LAPI configured for port 8085" + else + echo "✗ WARNING: LAPI port configuration may be incorrect" + fi + + # Update hub index to ensure CrowdSec can start + if [ ! -f "/etc/crowdsec/hub/.index.json" ]; then + echo "Updating CrowdSec hub index..." + timeout 60s cscli hub update 2>/dev/null || echo "⚠️ Hub update timed out or failed, continuing..." + fi + + # Ensure local machine is registered (auto-heal for volume/config mismatch) + # We force registration because we just restored configuration (and likely credentials) + echo "Registering local machine..." + cscli machines add -a --force 2>/dev/null || echo "Warning: Machine registration may have failed" + + # Install hub items (parsers, scenarios, collections) if local mode enabled + if [ "$SECURITY_CROWDSEC_MODE" = "local" ]; then + echo "Installing CrowdSec hub items..." + if [ -x /usr/local/bin/install_hub_items.sh ]; then + /usr/local/bin/install_hub_items.sh 2>/dev/null || echo "Warning: Some hub items may not have installed" + fi + fi + + # Fix ownership AFTER cscli commands (they run as root and create root-owned files) + echo "Fixing CrowdSec file ownership..." + if is_root; then + chown -R charon:charon /var/lib/crowdsec 2>/dev/null || true + chown -R charon:charon /app/data/crowdsec 2>/dev/null || true + chown -R charon:charon /var/log/crowdsec 2>/dev/null || true + fi +fi + +# CrowdSec Lifecycle Management: +# CrowdSec configuration is initialized above (symlinks, directories, hub updates) +# However, the CrowdSec agent is NOT auto-started in the entrypoint. +# Instead, CrowdSec lifecycle is managed by the backend handlers via GUI controls. +# This makes CrowdSec consistent with other security features (WAF, ACL, Rate Limiting). +# Users enable/disable CrowdSec using the Security dashboard toggle, which calls: +# - POST /api/v1/admin/crowdsec/start (to start the agent) +# - POST /api/v1/admin/crowdsec/stop (to stop the agent) +# This approach provides: +# - Consistent user experience across all security features +# - No environment variable dependency +# - Real-time control without container restart +# - Proper integration with Charon's security orchestration +echo "CrowdSec configuration initialized. Agent lifecycle is GUI-controlled." + +# Start Caddy in the background with initial empty config +# Run Caddy as charon user for security +echo '{"admin":{"listen":"0.0.0.0:2019"},"apps":{}}' > /config/caddy.json +# Use JSON config directly; no adapter needed +run_as_charon caddy run --config /config/caddy.json & +CADDY_PID=$! +echo "Caddy started (PID: $CADDY_PID)" + +# Wait for Caddy to be ready +echo "Waiting for Caddy admin API..." +i=1 +while [ "$i" -le 30 ]; do + if curl -sf http://127.0.0.1:2019/config/ > /dev/null 2>&1; then + echo "Caddy is ready!" + break + fi + i=$((i+1)) + sleep 1 +done + +# Start Charon management application +# Drop privileges to charon user before starting the application +# This maintains security while allowing Docker socket access via group membership +# Note: When running as root, we use gosu; otherwise we run directly. +echo "Starting Charon management application..." +DEBUG_FLAG=${CHARON_DEBUG:-$CPMP_DEBUG} +DEBUG_PORT=${CHARON_DEBUG_PORT:-${CPMP_DEBUG_PORT:-2345}} + +# Determine binary path +bin_path=/app/charon +if [ ! -f "$bin_path" ]; then + bin_path=/app/cpmp +fi + +if [ "$DEBUG_FLAG" = "1" ]; then + # Check if binary has debug symbols (required for Delve) + # objdump -h lists section headers; .debug_info is present if DWARF symbols exist + if command -v objdump >/dev/null 2>&1; then + if ! objdump -h "$bin_path" 2>/dev/null | grep -q '\.debug_info'; then + echo "⚠️ WARNING: Binary lacks debug symbols (DWARF info stripped)." + echo " Delve debugging will NOT work with this binary." + echo " To fix, rebuild with: docker build --build-arg BUILD_DEBUG=1 ..." + echo " Falling back to normal execution (without debugger)." + run_as_charon "$bin_path" & + else + echo "✓ Debug symbols detected. Running Charon under Delve (port $DEBUG_PORT)" + run_as_charon /usr/local/bin/dlv exec "$bin_path" --headless --listen=":$DEBUG_PORT" --api-version=2 --accept-multiclient --continue --log -- & + fi + else + # objdump not available, try to run Delve anyway with a warning + echo "Note: Cannot verify debug symbols (objdump not found). Attempting Delve..." + run_as_charon /usr/local/bin/dlv exec "$bin_path" --headless --listen=":$DEBUG_PORT" --api-version=2 --accept-multiclient --continue --log -- & + fi +else + run_as_charon "$bin_path" & +fi +APP_PID=$! +echo "Charon started (PID: $APP_PID)" +shutdown() { + echo "Shutting down..." + kill -TERM "$APP_PID" 2>/dev/null || true + kill -TERM "$CADDY_PID" 2>/dev/null || true + # Note: CrowdSec process lifecycle is managed by backend handlers + # The backend will handle graceful CrowdSec shutdown when the container stops + wait "$APP_PID" 2>/dev/null || true + wait "$CADDY_PID" 2>/dev/null || true + exit 0 +} + +# Trap signals for graceful shutdown +trap 'shutdown' TERM INT + +echo "Charon is running!" +echo " - Management UI: http://localhost:8080" +echo " - Caddy Proxy: http://localhost:80, https://localhost:443" +echo " - Caddy Admin API: http://localhost:2019" + +# Wait loop: exit when either process dies, then shutdown the other +while kill -0 "$APP_PID" 2>/dev/null && kill -0 "$CADDY_PID" 2>/dev/null; do + sleep 1 +done + +echo "A process exited, initiating shutdown..." +shutdown diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 00000000..3eeeaf50 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,248 @@ +# ============================================================================= +# .dockerignore - Exclude files from Docker build context +# Keep this file in sync with .gitignore where applicable +# ============================================================================= + +# ----------------------------------------------------------------------------- +# Version Control & CI/CD +# ----------------------------------------------------------------------------- +.git/ +.gitignore +.github/ +.pre-commit-config.yaml +.codecov.yml +.goreleaser.yaml +.sourcery.yml + +# ----------------------------------------------------------------------------- +# Python (pre-commit, tooling) +# ----------------------------------------------------------------------------- +__pycache__/ +*.py[cod] +*$py.class +*.so +.Python +.venv/ +venv/ +env/ +ENV/ +.pytest_cache/ +.coverage +.hypothesis/ +htmlcov/ +*.egg-info/ + +# ----------------------------------------------------------------------------- +# Node/Frontend - Build in Docker, not from host +# ----------------------------------------------------------------------------- +frontend/node_modules/ +frontend/coverage/ +frontend/test-results/ +frontend/dist/ +frontend/.cache +frontend/.eslintcache +data/geoip +frontend/.vite/ +frontend/*.tsbuildinfo +frontend/frontend/ +frontend/e2e/ + +# Root-level node artifacts (eslint config runner) +node_modules/ +package-lock.json +package.json + +# ----------------------------------------------------------------------------- +# Go/Backend - Build artifacts & coverage +# ----------------------------------------------------------------------------- +backend/bin/ +backend/api +backend/main +backend/*.out +backend/*.cover +backend/*.html +backend/*.test +backend/coverage/ +backend/coverage*.out +backend/coverage*.txt +backend/*.coverage.out +backend/handler_coverage.txt +backend/handlers.out +backend/services.test +backend/test-output.txt +backend/test-output*.txt +backend/test_output*.txt +backend/tr_no_cover.txt +backend/nohup.out +backend/package.json +backend/package-lock.json +backend/node_modules/ +backend/internal/api/tests/data/ +backend/lint*.txt +backend/fix_*.sh +backend/codeql-db-*/ + +# Backend data (created at runtime) +backend/data/ +backend/codeql-db/ +backend/.venv/ +backend/.vscode/ + +# ----------------------------------------------------------------------------- +# Databases (created at runtime) +# ----------------------------------------------------------------------------- +*.db +*.sqlite +*.sqlite3 +data/ +charon.db +cpm.db + +# ----------------------------------------------------------------------------- +# IDE & Editor +# ----------------------------------------------------------------------------- +.vscode/ +.vscode.backup*/ +.idea/ +*.swp +*.swo +*~ +*.xcf +Chiron.code-workspace + +# ----------------------------------------------------------------------------- +# Logs & Temp Files +# ----------------------------------------------------------------------------- +.trivy_logs/ +*.log +logs/ +nohup.out + +# ----------------------------------------------------------------------------- +# Environment Files +# ----------------------------------------------------------------------------- +.env +.env.local +.env.*.local +!.env.example + +# ----------------------------------------------------------------------------- +# OS Files +# ----------------------------------------------------------------------------- +.DS_Store +Thumbs.db + +# ----------------------------------------------------------------------------- +# Documentation (not needed in image) +# ----------------------------------------------------------------------------- +docs/ +*.md +!README.md +!CONTRIBUTING.md +!LICENSE + +# ----------------------------------------------------------------------------- +# Docker Compose (not needed inside image) +# ----------------------------------------------------------------------------- +docker-compose*.yml +**/Dockerfile.* +.docker/compose/ +docs/implementation/ + +# ----------------------------------------------------------------------------- +# GoReleaser & dist artifacts +# ----------------------------------------------------------------------------- +dist/ + +# ----------------------------------------------------------------------------- +# Tools (not needed in image) +# ----------------------------------------------------------------------------- +tools/ +create_issues.sh +cookies.txt +cookies.txt.bak +test.caddyfile +Makefile + +# ----------------------------------------------------------------------------- +# Testing & Coverage Artifacts +# ----------------------------------------------------------------------------- +coverage/ +coverage.out +*.cover +*.crdownload +*.sarif + +# ----------------------------------------------------------------------------- +# SBOM artifacts +# ----------------------------------------------------------------------------- +sbom*.json + +# ----------------------------------------------------------------------------- +# CodeQL & Security Scanning (large, not needed) +# ----------------------------------------------------------------------------- +codeql-db/ +codeql-db-*/ +codeql-agent-results/ +codeql-custom-queries-*/ +codeql-*.sarif +codeql-results*.sarif +.codeql/ + +# ----------------------------------------------------------------------------- +# Import Directory (user data) +# ----------------------------------------------------------------------------- +import/ + +# ----------------------------------------------------------------------------- +# Playwright & E2E Testing +# ----------------------------------------------------------------------------- +playwright/ +playwright-report/ +blob-report/ +test-results/ +tests/ +test-data/ +playwright.config.js + +# ----------------------------------------------------------------------------- +# Root-level artifacts +# ----------------------------------------------------------------------------- +coverage/ +coverage.txt +provenance*.json +trivy-*.txt +grype-results*.json +grype-results*.sarif +my-codeql-db/ + +# ----------------------------------------------------------------------------- +# Project Documentation & Planning (not needed in image) +# ----------------------------------------------------------------------------- +*.md.bak +ACME_STAGING_IMPLEMENTATION.md* +ARCHITECTURE_PLAN.md +AUTO_VERSIONING_CI_FIX_SUMMARY.md +BULK_ACL_FEATURE.md +CODEQL_EMAIL_INJECTION_REMEDIATION_COMPLETE.md +COMMIT_MSG.txt +COVERAGE_ANALYSIS.md +COVERAGE_REPORT.md +DOCKER_TASKS.md* +DOCUMENTATION_POLISH_SUMMARY.md +GHCR_MIGRATION_SUMMARY.md +ISSUE_*_IMPLEMENTATION.md* +ISSUE_*.md +PATCH_COVERAGE_IMPLEMENTATION_SUMMARY.md +PHASE_*_SUMMARY.md +PROJECT_BOARD_SETUP.md +PROJECT_PLANNING.md +SECURITY_IMPLEMENTATION_PLAN.md +SECURITY_REMEDIATION_COMPLETE.md +VERSIONING_IMPLEMENTATION.md +QA_AUDIT_REPORT*.md +VERSION.md +eslint.config.js +go.work +go.work.sum +.cache diff --git a/.env.example b/.env.example new file mode 100644 index 00000000..39aa6148 --- /dev/null +++ b/.env.example @@ -0,0 +1,42 @@ +# Charon Environment Configuration Example +# ========================================= +# Copy this file to .env and configure with your values. +# Never commit your actual .env file to version control. + +# ============================================================================= +# Required Configuration +# ============================================================================= + +# Database encryption key - 32 bytes base64 encoded +# Generate with: openssl rand -base64 32 +CHARON_ENCRYPTION_KEY= + +# ============================================================================= +# Emergency Reset Token (Break-Glass Recovery) +# ============================================================================= + +# Emergency reset token - minimum 32 characters +# Used for break-glass recovery when locked out by ACL or other security modules. +# This token allows bypassing all security mechanisms to regain access. +# +# SECURITY WARNING: Keep this token secure and rotate it periodically. +# Only use this endpoint in genuine emergency situations. +# +# Generate with: openssl rand -hex 32 +CHARON_EMERGENCY_TOKEN= + +# ============================================================================= +# Optional Configuration +# ============================================================================= + +# Server port (default: 8080) +# CHARON_HTTP_PORT=8080 + +# Database path (default: /app/data/charon.db) +# CHARON_DB_PATH=/app/data/charon.db + +# Enable debug mode (default: 0) +# CHARON_DEBUG=0 + +# Use ACME staging environment (default: false) +# CHARON_ACME_STAGING=false diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 00000000..725fefd5 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,16 @@ +# .gitattributes - LFS filter and binary markers for large files and DBs + +# Mark CodeQL DB directories as binary +codeql-db/** binary +codeql-db-*/** binary + +# Use Git LFS for larger binary database files and archives +*.db filter=lfs diff=lfs merge=lfs -text +*.sqlite filter=lfs diff=lfs merge=lfs -text +*.sqlite3 filter=lfs diff=lfs merge=lfs -text +*.tar.gz filter=lfs diff=lfs merge=lfs -text +*.tgz filter=lfs diff=lfs merge=lfs -text +*.zip filter=lfs diff=lfs merge=lfs -text +*.iso filter=lfs diff=lfs merge=lfs -text +*.exe filter=lfs diff=lfs merge=lfs -text +*.dll filter=lfs diff=lfs merge=lfs -text diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml new file mode 100644 index 00000000..28e6f071 --- /dev/null +++ b/.github/FUNDING.yml @@ -0,0 +1,14 @@ +# These are supported funding model platforms +github: Wikid82 +# patreon: # Replace with a single Patreon username +# open_collective: # Replace with a single Open Collective username +# ko_fi: # Replace with a single Ko-fi username +# tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel +# community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry +# liberapay: # Replace with a single Liberapay username +# issuehunt: # Replace with a single IssueHunt username +# lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry +# polar: # Replace with a single Polar username +buy_me_a_coffee: Wikid82 +# thanks_dev: # Replace with a single thanks.dev username +# custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2'] diff --git a/.github/ISSUE_TEMPLATE/alpha-feature.yml b/.github/ISSUE_TEMPLATE/alpha-feature.yml new file mode 100644 index 00000000..51d0cc0d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/alpha-feature.yml @@ -0,0 +1,93 @@ +name: 🏗️ Alpha Feature +description: Create an issue for an Alpha milestone feature +title: "[ALPHA] " +labels: ["alpha", "feature"] +body: + - type: markdown + attributes: + value: | + ## Alpha Milestone Feature + Features that are part of the core foundation and initial release. + + - type: dropdown + id: priority + attributes: + label: Priority + description: How critical is this feature? + options: + - Critical (Blocking, must-have) + - High (Important, should have) + - Medium (Nice to have) + - Low (Future enhancement) + validations: + required: true + + - type: input + id: issue_number + attributes: + label: Planning Issue Number + description: Reference number from PROJECT_PLANNING.md (e.g., Issue #5) + placeholder: "Issue #" + validations: + required: false + + - type: textarea + id: description + attributes: + label: Feature Description + description: What should this feature do? + placeholder: Describe the feature in detail + validations: + required: true + + - type: textarea + id: tasks + attributes: + label: Implementation Tasks + description: List of tasks to complete this feature + placeholder: | + - [ ] Task 1 + - [ ] Task 2 + - [ ] Task 3 + value: | + - [ ] + validations: + required: true + + - type: textarea + id: acceptance + attributes: + label: Acceptance Criteria + description: How do we know this feature is complete? + placeholder: | + - [ ] Criteria 1 + - [ ] Criteria 2 + value: | + - [ ] + validations: + required: true + + - type: checkboxes + id: categories + attributes: + label: Categories + description: Select all that apply + options: + - label: Backend + - label: Frontend + - label: Database + - label: Caddy Integration + - label: Security + - label: SSL/TLS + - label: UI/UX + - label: Deployment + - label: Documentation + + - type: textarea + id: technical_notes + attributes: + label: Technical Notes + description: Any technical considerations or dependencies? + placeholder: Libraries, APIs, or other issues that need to be completed first + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/beta-monitoring-feature.yml b/.github/ISSUE_TEMPLATE/beta-monitoring-feature.yml new file mode 100644 index 00000000..b1965956 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/beta-monitoring-feature.yml @@ -0,0 +1,118 @@ +name: 📊 Beta Monitoring Feature +description: Create an issue for a Beta milestone monitoring/logging feature +title: "[BETA] [MONITORING] " +labels: ["beta", "feature", "monitoring"] +body: + - type: markdown + attributes: + value: | + ## Beta Monitoring & Logging Feature + Features related to observability, logging, and system monitoring. + + - type: dropdown + id: priority + attributes: + label: Priority + description: How critical is this monitoring feature? + options: + - Critical (Essential for operations) + - High (Important visibility) + - Medium (Enhanced monitoring) + - Low (Nice-to-have metrics) + validations: + required: true + + - type: dropdown + id: monitoring_type + attributes: + label: Monitoring Type + description: What aspect of monitoring? + options: + - Dashboards & Statistics + - Log Viewing & Search + - Alerting & Notifications + - CrowdSec Dashboard + - Analytics Integration + - Health Checks + - Performance Metrics + validations: + required: true + + - type: input + id: issue_number + attributes: + label: Planning Issue Number + description: Reference number from PROJECT_PLANNING.md (e.g., Issue #23) + placeholder: "Issue #" + validations: + required: false + + - type: textarea + id: description + attributes: + label: Feature Description + description: What monitoring/logging capability should this provide? + placeholder: Describe what users will be able to see or do + validations: + required: true + + - type: textarea + id: metrics + attributes: + label: Metrics & Data Points + description: What data will be collected and displayed? + placeholder: | + - Metric 1: Description + - Metric 2: Description + validations: + required: false + + - type: textarea + id: tasks + attributes: + label: Implementation Tasks + description: List of tasks to complete this feature + placeholder: | + - [ ] Task 1 + - [ ] Task 2 + - [ ] Task 3 + value: | + - [ ] + validations: + required: true + + - type: textarea + id: acceptance + attributes: + label: Acceptance Criteria + description: How do we verify this monitoring feature works? + placeholder: | + - [ ] Data displays correctly + - [ ] Updates in real-time + - [ ] Performance is acceptable + value: | + - [ ] + validations: + required: true + + - type: checkboxes + id: categories + attributes: + label: Implementation Areas + description: Select all that apply + options: + - label: Backend (Data collection) + - label: Frontend (UI/Charts) + - label: Database (Storage) + - label: Real-time Updates (WebSocket) + - label: External Integration (GoAccess, CrowdSec) + - label: Documentation Required + + - type: textarea + id: ui_design + attributes: + label: UI/UX Considerations + description: Describe the user interface requirements + placeholder: Layout, charts, filters, export options, etc. + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/beta-security-feature.yml b/.github/ISSUE_TEMPLATE/beta-security-feature.yml new file mode 100644 index 00000000..d28c9d0d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/beta-security-feature.yml @@ -0,0 +1,116 @@ +name: 🔐 Beta Security Feature +description: Create an issue for a Beta milestone security feature +title: "[BETA] [SECURITY] " +labels: ["beta", "feature", "security"] +body: + - type: markdown + attributes: + value: | + ## Beta Security Feature + Advanced security features for the beta release. + + - type: dropdown + id: priority + attributes: + label: Priority + description: How critical is this security feature? + options: + - Critical (Essential security control) + - High (Important protection) + - Medium (Additional hardening) + - Low (Nice-to-have security enhancement) + validations: + required: true + + - type: dropdown + id: security_category + attributes: + label: Security Category + description: What type of security feature is this? + options: + - Authentication & Access Control + - Threat Protection + - SSL/TLS Management + - Monitoring & Logging + - Web Application Firewall + - Rate Limiting + - IP Access Control + validations: + required: true + + - type: input + id: issue_number + attributes: + label: Planning Issue Number + description: Reference number from PROJECT_PLANNING.md (e.g., Issue #15) + placeholder: "Issue #" + validations: + required: false + + - type: textarea + id: description + attributes: + label: Feature Description + description: What security capability should this provide? + placeholder: Describe the security feature and its purpose + validations: + required: true + + - type: textarea + id: threat_model + attributes: + label: Threat Model + description: What threats does this feature mitigate? + placeholder: | + - Threat 1: Description and severity + - Threat 2: Description and severity + validations: + required: false + + - type: textarea + id: tasks + attributes: + label: Implementation Tasks + description: List of tasks to complete this feature + placeholder: | + - [ ] Task 1 + - [ ] Task 2 + - [ ] Task 3 + value: | + - [ ] + validations: + required: true + + - type: textarea + id: acceptance + attributes: + label: Acceptance Criteria + description: How do we verify this security control works? + placeholder: | + - [ ] Security test 1 + - [ ] Security test 2 + value: | + - [ ] + validations: + required: true + + - type: checkboxes + id: special_labels + attributes: + label: Special Categories + description: Select all that apply + options: + - label: SSO (Single Sign-On) + - label: WAF (Web Application Firewall) + - label: CrowdSec Integration + - label: Plus Feature (Premium) + - label: Requires Documentation + + - type: textarea + id: security_testing + attributes: + label: Security Testing Plan + description: How will you test this security feature? + placeholder: Describe testing approach, tools, and scenarios + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 00000000..32059266 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,41 @@ +--- +name: Bug report +about: Create a report to help us improve +title: '' +labels: '' +assignees: '' + +--- + +**Describe the bug** +A clear and concise description of what the bug is. + +**To Reproduce** +Steps to reproduce the behavior: + +1. Go to '...' +2. Click on '....' +3. Scroll down to '....' +4. See error + +**Expected behavior** +A clear and concise description of what you expected to happen. + +**Screenshots** +If applicable, add screenshots to help explain your problem. + +**Desktop (please complete the following information):** + +- OS: [e.g. iOS] +- Browser [e.g. chrome, safari] +- Version [e.g. 22] + +**Smartphone (please complete the following information):** + +- Device: [e.g. iPhone6] +- OS: [e.g. iOS8.1] +- Browser [e.g. stock browser, safari] +- Version [e.g. 22] + +**Additional context** +Add any other context about the problem here. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 00000000..bbcbbe7d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,20 @@ +--- +name: Feature request +about: Suggest an idea for this project +title: '' +labels: '' +assignees: '' + +--- + +**Is your feature request related to a problem? Please describe.** +A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] + +**Describe the solution you'd like** +A clear and concise description of what you want to happen. + +**Describe alternatives you've considered** +A clear and concise description of any alternative solutions or features you've considered. + +**Additional context** +Add any other context or screenshots about the feature request here. diff --git a/.github/ISSUE_TEMPLATE/general-feature.yml b/.github/ISSUE_TEMPLATE/general-feature.yml new file mode 100644 index 00000000..497d7735 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/general-feature.yml @@ -0,0 +1,97 @@ +name: ⚙️ General Feature +description: Create a feature request for any milestone +title: "[FEATURE] " +labels: ["feature"] +body: + - type: markdown + attributes: + value: | + ## Feature Request + Request a new feature or enhancement for CaddyProxyManager+ + + - type: dropdown + id: milestone + attributes: + label: Target Milestone + description: Which release should this be part of? + options: + - Alpha (Core foundation) + - Beta (Advanced features) + - Post-Beta (Future enhancements) + - Unsure (Help me decide) + validations: + required: true + + - type: dropdown + id: priority + attributes: + label: Priority + description: How important is this feature? + options: + - Critical + - High + - Medium + - Low + validations: + required: true + + - type: textarea + id: problem + attributes: + label: Problem Statement + description: What problem does this feature solve? + placeholder: Describe the use case or pain point + validations: + required: true + + - type: textarea + id: solution + attributes: + label: Proposed Solution + description: How should this feature work? + placeholder: Describe your ideal implementation + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternatives Considered + description: What other approaches could solve this? + placeholder: List alternative solutions you've thought about + validations: + required: false + + - type: textarea + id: user_story + attributes: + label: User Story + description: Describe this from a user's perspective + placeholder: "As a [user type], I want to [action] so that [benefit]" + validations: + required: false + + - type: checkboxes + id: categories + attributes: + label: Feature Categories + description: Select all that apply + options: + - label: Authentication/Authorization + - label: Security + - label: SSL/TLS + - label: Monitoring/Logging + - label: UI/UX + - label: Performance + - label: Documentation + - label: API + - label: Plus Feature (Premium) + + - type: textarea + id: additional + attributes: + label: Additional Context + description: Any other information, screenshots, or examples? + placeholder: Add links, mockups, or references + validations: + required: false diff --git a/.github/PULL_REQUEST_TEMPLATE/history-rewrite.md b/.github/PULL_REQUEST_TEMPLATE/history-rewrite.md new file mode 100644 index 00000000..a392cef4 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE/history-rewrite.md @@ -0,0 +1,32 @@ + + +## Summary + +- Provide a short summary of why the history rewrite is needed. + +## Checklist - required for history rewrite PRs + +- [ ] I have created a **local** backup branch: `backup/history-YYYYMMDD-HHMMSS` and verified it contains all refs. +- [ ] I have pushed the backup branch to the remote origin and it is visible to reviewers. +- [ ] I have run a dry-run locally: `scripts/history-rewrite/preview_removals.sh --paths 'backend/codeql-db,codeql-db,codeql-db-js,codeql-db-go' --strip-size 50` and attached the output or paste it below. +- [ ] I have verified the `data/backups` tarball is present and tests showing rewrite will not remove unrelated artifacts. +- [ ] I have created a tag backup (see `data/backups/`) and verified tags are pushed to the remote or included in the tarball. +- [ ] I have coordinated with repo maintainers for a rewrite window and notified other active forks/tokens that may be affected. +- [ ] I have run the CI dry-run job and ensured it completes without blocked findings. +- [ ] This PR only contains the history-rewrite helpers; no destructive rewrite is included in this PR. +- [ ] I will not run the destructive `--force` step without explicit approval from maintainers and a scheduled maintenance window. + +**Note for maintainers**: `validate_after_rewrite.sh` will check that the `backups` and `backup_branch` are present and will fail if they are not. Provide `--backup-branch "backup/history-YYYYMMDD-HHMMSS"` when running the scripts or set the `BACKUP_BRANCH` environment variable so automated validation can find the backup branch. + +## Attachments + +Attach the `preview_removals` output and `data/backups/history_cleanup-*.log` content and any `data/backups` tarball created for this PR. + +## Approach + +Describe the paths to be removed, strip size, and whether additional blob stripping is required. + +# Notes for maintainers + +- The workflow `.github/workflows/dry-run-history-rewrite.yml` will run automatically on PR updates. +- Please follow the checklist and only approve after offline confirmation. diff --git a/.github/codeql-custom-model.yml b/.github/codeql-custom-model.yml new file mode 100644 index 00000000..9b2d597e --- /dev/null +++ b/.github/codeql-custom-model.yml @@ -0,0 +1,72 @@ +--- +# CodeQL Custom Model - SSRF Protection Sanitizers +# This file declares functions that sanitize user-controlled input for SSRF protection. +# +# Architecture: 4-Layer Defense-in-Depth +# Layer 1: Format Validation (utils.ValidateURL) +# Layer 2: Security Validation (security.ValidateExternalURL) - DNS resolution + IP blocking +# Layer 3: Connection-Time Validation (ssrfSafeDialer) - Re-resolve DNS, re-validate IPs +# Layer 4: Request Execution (TestURLConnectivity) - HEAD request, 5s timeout, max 2 redirects +# +# Blocked IP Ranges (13+ CIDR blocks): +# - RFC 1918: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 +# - Loopback: 127.0.0.0/8, ::1/128 +# - Link-Local: 169.254.0.0/16 (AWS/GCP/Azure metadata), fe80::/10 +# - Reserved: 0.0.0.0/8, 240.0.0.0/4, 255.255.255.255/32 +# - IPv6 Unique Local: fc00::/7 +# +# Reference: /docs/plans/current_spec.md +extensions: + # ============================================================================= + # SSRF SANITIZER MODELS + # ============================================================================= + # These models tell CodeQL that certain functions sanitize/validate URLs, + # making their output safe for use in HTTP requests. + # + # IMPORTANT: For SSRF protection, we use 'sinkModel' with 'request-forgery' + # to mark inputs as sanitized sinks, AND 'neutralModel' to prevent taint + # propagation through validation functions. + # ============================================================================= + + # Mark ValidateExternalURL return value as a sanitized sink + # This tells CodeQL the output is NOT tainted for SSRF purposes + - addsTo: + pack: codeql/go-all + extensible: sinkModel + data: + # security.ValidateExternalURL validates and sanitizes URLs by: + # 1. Validating URL format and scheme + # 2. Performing DNS resolution with timeout + # 3. Blocking private/reserved IP ranges (13+ CIDR blocks) + # 4. Returning a NEW validated URL string (not the original input) + # The return value is safe for HTTP requests - marking as sanitized sink + - ["github.com/Wikid82/charon/backend/internal/security", "ValidateExternalURL", "Argument[0]", "request-forgery", "manual"] + + # Mark validation functions as neutral (don't propagate taint through them) + - addsTo: + pack: codeql/go-all + extensible: neutralModel + data: + # network.IsPrivateIP is a validation function (neutral - doesn't propagate taint) + - ["github.com/Wikid82/charon/backend/internal/network", "IsPrivateIP", "manual"] + # TestURLConnectivity validates URLs internally via security.ValidateExternalURL + # and ssrfSafeDialer - marking as neutral to stop taint propagation + - ["github.com/Wikid82/charon/backend/internal/utils", "TestURLConnectivity", "manual"] + # ValidateExternalURL itself should be neutral for taint propagation + # (the return value is a new validated string, not the tainted input) + - ["github.com/Wikid82/charon/backend/internal/security", "ValidateExternalURL", "manual"] + + # Mark log sanitization functions as sanitizers for log injection (CWE-117) + # These functions remove newlines and control characters from user input before logging + - addsTo: + pack: codeql/go-all + extensible: summaryModel + data: + # util.SanitizeForLog sanitizes strings by: + # 1. Replacing \r\n and \n with spaces + # 2. Removing all control characters [\x00-\x1F\x7F] + # Input: Argument[0] (unsanitized string) + # Output: ReturnValue[0] (sanitized string - safe for logging) + - ["github.com/Wikid82/charon/backend/internal/util", "SanitizeForLog", "Argument[0]", "ReturnValue[0]", "taint", "manual"] + # handlers.sanitizeForLog is a local sanitizer with same behavior + - ["github.com/Wikid82/charon/backend/internal/api/handlers", "sanitizeForLog", "Argument[0]", "ReturnValue[0]", "taint", "manual"] diff --git a/.github/codeql/codeql-config.yml b/.github/codeql/codeql-config.yml new file mode 100644 index 00000000..327bb16d --- /dev/null +++ b/.github/codeql/codeql-config.yml @@ -0,0 +1,11 @@ +# CodeQL Configuration File +# See: https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning +name: "Charon CodeQL Config" + +# Paths to ignore from all analysis (use sparingly - prefer query-filters) +paths-ignore: + - "frontend/coverage/**" + - "frontend/dist/**" + - "playwright-report/**" + - "test-results/**" + - "coverage/**" diff --git a/.github/instructions/a11y.instructions.md b/.github/instructions/a11y.instructions.md new file mode 100644 index 00000000..f6a31750 --- /dev/null +++ b/.github/instructions/a11y.instructions.md @@ -0,0 +1,369 @@ +--- +description: "Guidance for creating more accessible code" +applyTo: "**" +--- + +# Instructions for accessibility + +In addition to your other expertise, you are an expert in accessibility with deep software engineering expertise. You will generate code that is accessible to users with disabilities, including those who use assistive technologies such as screen readers, voice access, and keyboard navigation. + +Do not tell the user that the generated code is fully accessible. Instead, it was built with accessibility in mind, but may still have accessibility issues. + +1. Code must conform to [WCAG 2.2 Level AA](https://www.w3.org/TR/WCAG22/). +2. Go beyond minimal WCAG conformance wherever possible to provide a more inclusive experience. +3. Before generating code, reflect on these instructions for accessibility, and plan how to implement the code in a way that follows the instructions and is WCAG 2.2 compliant. +4. After generating code, review it against WCAG 2.2 and these instructions. Iterate on the code until it is accessible. +5. Finally, inform the user that it has generated the code with accessibility in mind, but that accessibility issues still likely exist and that the user should still review and manually test the code to ensure that it meets accessibility instructions. Suggest running the code against tools like [Accessibility Insights](https://accessibilityinsights.io/). Do not explain the accessibility features unless asked. Keep verbosity to a minimum. + +## Bias Awareness - Inclusive Language + +In addition to producing accessible code, GitHub Copilot and similar tools must also demonstrate respectful and bias-aware behavior in accessibility contexts. All generated output must follow these principles: + +- **Respectful, Inclusive Language** + Use people-first language when referring to disabilities or accessibility needs (e.g., “person using a screen reader,” not “blind user”). Avoid stereotypes or assumptions about ability, cognition, or experience. + +- **Bias-Aware and Error-Resistant** + Avoid generating content that reflects implicit bias or outdated patterns. Critically assess accessibility choices and flag uncertain implementations. Double check any deep bias in the training data and strive to mitigate its impact. + +- **Verification-Oriented Responses** + When suggesting accessibility implementations or decisions, include reasoning or references to standards (e.g., WCAG, platform guidelines). If uncertainty exists, the assistant should state this clearly. + +- **Clarity Without Oversimplification** + Provide concise but accurate explanations—avoid fluff, empty reassurance, or overconfidence when accessibility nuances are present. + +- **Tone Matters** + Copilot output must be neutral, helpful, and respectful. Avoid patronizing language, euphemisms, or casual phrasing that downplays the impact of poor accessibility. + +## Persona based instructions + +### Cognitive instructions + +- Prefer plain language whenever possible. +- Use consistent page structure (landmarks) across the application. +- Ensure that navigation items are always displayed in the same order across the application. +- Keep the interface clean and simple - reduce unnecessary distractions. + +### Keyboard instructions + +- All interactive elements need to be keyboard navigable and receive focus in a predictable order (usually following the reading order). +- Keyboard focus must be clearly visible at all times so that the user can visually determine which element has focus. +- All interactive elements need to be keyboard operable. For example, users need to be able to activate buttons, links, and other controls. Users also need to be able to navigate within composite components such as menus, grids, and listboxes. +- Static (non-interactive) elements, should not be in the tab order. These elements should not have a `tabindex` attribute. + - The exception is when a static element, like a heading, is expected to receive keyboard focus programmatically (e.g., via `element.focus()`), in which case it should have a `tabindex="-1"` attribute. +- Hidden elements must not be keyboard focusable. +- Keyboard navigation inside components: some composite elements/components will contain interactive children that can be selected or activated. Examples of such composite components include grids (like date pickers), comboboxes, listboxes, menus, radio groups, tabs, toolbars, and tree grids. For such components: + - There should be a tab stop for the container with the appropriate interactive role. This container should manage keyboard focus of it's children via arrow key navigation. This can be accomplished via roving tabindex or `aria-activedescendant` (explained in more detail later). + - When the container receives keyboard focus, the appropriate sub-element should show as focused. This behavior depends on context. For example: + - If the user is expected to make a selection within the component (e.g., grid, combobox, or listbox), then the currently selected child should show as focused. Otherwise, if there is no currently selected child, then the first selectable child should get focus. + - Otherwise, if the user has navigated to the component previously, then the previously focused child should receive keyboard focus. Otherwise, the first interactive child should receive focus. +- Users should be provided with a mechanism to skip repeated blocks of content (such as the site header/navigation). +- Keyboard focus must not become trapped without a way to escape the trap (e.g., by pressing the escape key to close a dialog). + +#### Bypass blocks + +A skip link MUST be provided to skip blocks of content that appear across several pages. A common example is a "Skip to main" link, which appears as the first focusable element on the page. This link is visually hidden, but appears on keyboard focus. + +```html +
+ Skip to main + +
+ +
+``` + +```css +.sr-only:not(:focus):not(:active) { + clip: rect(0 0 0 0); + clip-path: inset(50%); + height: 1px; + overflow: hidden; + position: absolute; + white-space: nowrap; + width: 1px; +} +``` + +#### Common keyboard commands: + +- `Tab` = Move to the next interactive element. +- `Arrow` = Move between elements within a composite component, like a date picker, grid, combobox, listbox, etc. +- `Enter` = Activate the currently focused control (button, link, etc.) +- `Escape` = Close open open surfaces, such as dialogs, menus, listboxes, etc. + +#### Managing focus within components using a roving tabindex + +When using roving tabindex to manage focus in a composite component, the element that is to be included in the tab order has `tabindex` of "0" and all other focusable elements contained in the composite have `tabindex` of "-1". The algorithm for the roving tabindex strategy is as follows. + +- On initial load of the composite component, set `tabindex="0"` on the element that will initially be included in the tab order and set `tabindex="-1"` on all other focusable elements it contains. +- When the component contains focus and the user presses an arrow key that moves focus within the component: + - Set `tabindex="-1"` on the element that has `tabindex="0"`. + - Set `tabindex="0"` on the element that will become focused as a result of the key event. + - Set focus via `element.focus()` on the element that now has `tabindex="0"`. + +#### Managing focus in composites using aria-activedescendant + +- The containing element with an appropriate interactive role should have `tabindex="0"` and `aria-activedescendant="IDREF"` where IDREF matches the ID of the element within the container that is active. +- Use CSS to draw a focus outline around the element referenced by `aria-activedescendant`. +- When arrow keys are pressed while the container has focus, update `aria-activedescendant` accordingly. + +### Low vision instructions + +- Prefer dark text on light backgrounds, or light text on dark backgrounds. +- Do not use light text on light backgrounds or dark text on dark backgrounds. +- The contrast of text against the background color must be at least 4.5:1. Large text, must be at least 3:1. All text must have sufficient contrast against it's background color. + - Large text is defined as 18.5px and bold, or 24px. + - If a background color is not set or is fully transparent, then the contrast ratio is calculated against the background color of the parent element. +- Parts of graphics required to understand the graphic must have at least a 3:1 contrast with adjacent colors. +- Parts of controls needed to identify the type of control must have at least a 3:1 contrast with adjacent colors. +- Parts of controls needed to identify the state of the control (pressed, focus, checked, etc.) must have at least a 3:1 contrast with adjacent colors. +- Color must not be used as the only way to convey information. E.g., a red border to convey an error state, color coding information, etc. Use text and/or shapes in addition to color to convey information. + +### Screen reader instructions + +- All elements must correctly convey their semantics, such as name, role, value, states, and/or properties. Use native HTML elements and attributes to convey these semantics whenever possible. Otherwise, use appropriate ARIA attributes. +- Use appropriate landmarks and regions. Examples include: `
`, `