Security

Security best practices for using gitlab-summary safely in your organization.

Token Security

Token Scopes

Minimum Required: read_api

This scope allows gitlab-summary to:

  • ✅ Read pipeline data
  • ✅ Read job logs
  • ✅ Read group information
  • ✅ Read project metadata

This scope does NOT allow:

  • ❌ Modifying code
  • ❌ Triggering pipelines
  • ❌ Changing settings
  • ❌ Accessing secrets
  • ❌ Writing to repository

Token Storage

macOS - Keychain

Storage: macOS Keychain (system-level encryption)

Security Features:

  • Encrypted at rest
  • Per-user isolation
  • System-level access control
  • Survives system restarts

Manual Access:

  # View (requires password)
security find-generic-password -s "gitlab-summary" -a "gitlab-token"

# Delete
security delete-generic-password -s "gitlab-summary" -a "gitlab-token"

Windows - DPAPI

Storage: Data Protection API (DPAPI)

Security Features:

  • Encrypted per-user account
  • Cannot be decrypted by other users
  • Tied to Windows user profile
  • Transparent encryption/decryption

Location: %USERPROFILE%\.gitlab-summary\protected-token.dat

Linux - DataProtection

Storage: File-based with .NET DataProtection

Security Features:

  • Encrypted using key derivation
  • Keys stored separately
  • File permissions enforced (0600)

Locations:

  • Token: ~/.gitlab-summary/protected-token.dat
  • Keys: ~/.microsoft/usersecrets/

Recommended Permissions:

  chmod 700 ~/.gitlab-summary
chmod 600 ~/.gitlab-summary/protected-token.dat

Token Management Best Practices

✅ DO

Use Minimal Scopes:

  # Only read_api, nothing more
Scopes: [x] read_api
        [ ] api
        [ ] write_repository

Set Expiration Dates:

  • Personal tokens: 90 days
  • Automation tokens: 1 year maximum
  • Rotate before expiration

Use Group Tokens for Teams:

  # Instead of sharing personal token
# Create group access token
Group Settings → Access Tokens → Create
Role: Reporter
Scopes: read_api

Rotate Compromised Tokens Immediately:

  # 1. Revoke in GitLab
# 2. Clear from gitlab-summary
gitlab-summary token clear

# 3. Create new token
# 4. Store new token
gitlab-summary token set --url https://gitlab.example.com

Monitor Token Usage:

  • Check GitLab audit logs
  • Review access patterns
  • Revoke unused tokens

❌ DON’T

Never Commit Tokens:

  # ❌ NEVER DO THIS
git commit -m "Add token: glpat-xxxxxxxxxxxxxxxxxxxx"

# ❌ NEVER DO THIS
echo "TOKEN=glpat-xxx" > .env
git add .env

Never Share Tokens:

  # ❌ Bad: Sending token directly
slack send "Here's the token: glpat-xxx"

# ✅ Good: Share setup instructions
slack send "Create your own token at: https://gitlab.com/-/profile/personal_access_tokens"

Never Use Admin Tokens:

  # ❌ Too much privilege
Role: Owner, Admin, Maintainer

# ✅ Minimum required
Role: Reporter

Never Store in Plain Text:

  # ❌ Never do this
echo "glpat-xxx" > ~/gitlab-token.txt

# ✅ Use gitlab-summary's secure storage
gitlab-summary token set --url https://gitlab.example.com

Never Log Tokens:

  # ❌ Don't include in logs
echo "Using token: $GITLAB_TOKEN"

# ✅ Mask in logs
echo "Using token: ${GITLAB_TOKEN:0:8}...${GITLAB_TOKEN: -4}"

Network Security

HTTPS Enforcement

Always use HTTPS in production:

  # ✅ Production
gitlab-summary url set --url https://gitlab.company.com

# ❌ Never in production
gitlab-summary url set --url http://gitlab.company.com

Exception: Localhost development only

  # ✅ OK for local development
gitlab-summary url set --url http://localhost:8080

Certificate Validation

gitlab-summary validates SSL certificates by default.

Self-Signed Certificates:

  • Install proper CA certificates
  • Use organization’s PKI
  • Don’t disable validation in production

Firewall Configuration

Outbound (gitlab-summary → GitLab):

  • Port 443 (HTTPS)
  • Allow API endpoint: {gitlab-url}/api/v4/*

Inbound (Dashboard Server):

  • Port 5100 (default, configurable)
  • Only bind to localhost for single-user: --bind 127.0.0.1
  • Use reverse proxy (nginx/Apache) for team dashboards

Dashboard Security

Local Access Only (Default)

By default, dashboard binds to localhost:

  gitlab-summary serve --group my-org
# Accessible only from: http://localhost:5100

Security: Only current user can access

Team Dashboard (With Caution)

If deploying for team access:

Option 1: Reverse Proxy (Recommended)

  # nginx configuration
server {
    listen 443 ssl;
    server_name gitlab-dashboard.company.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location / {
        proxy_pass http://localhost:5100;
        auth_basic "GitLab Dashboard";
        auth_basic_user_file /etc/nginx/.htpasswd;
    }
}

Option 2: VPN/Internal Network

  • Deploy on internal network only
  • Require VPN access
  • Use network segmentation

Option 3: SSH Tunnel

  # User's machine
ssh -L 5100:localhost:5100 server.company.com

# Access locally at http://localhost:5100

AI Analysis Security

Data Sent to GitHub Copilot

Included:

  • Job log output (build/test logs)
  • Job metadata (name, stage)
  • Project/pipeline IDs (not names)
  • Custom system prompt

NOT Included:

  • Source code (unless in logs)
  • Git commit diffs
  • Other job logs
  • Environment variables (unless logged)
  • Team member information
  • GitLab credentials

Privacy Considerations

Before using AI analysis:

  1. Review your organization’s AI usage policy
  2. Check if logs contain sensitive data
  3. Understand GitHub Copilot privacy terms
  4. Consider if logs contain:
    • Customer data
    • Internal URLs/IPs
    • Service credentials
    • Proprietary information

Sensitive Logs: Don’t use AI analysis if logs contain:

  • Database connection strings
  • API keys in error messages
  • Customer PII
  • Internal infrastructure details

GitHub Copilot Privacy: https://docs.github.com/en/copilot/privacy

File System Security

Configuration Directory

Location: ~/.gitlab-summary/

Recommended Permissions:

  # Directory
chmod 700 ~/.gitlab-summary

# Settings file
chmod 600 ~/.gitlab-summary/settings.json

# Token file (Linux)
chmod 600 ~/.gitlab-summary/protected-token.dat

# Cache file
chmod 600 ~/.gitlab-summary/ai-analysis-cache.json

Verify:

  ls -la ~/.gitlab-summary/
# Should show: drwx------ (700) for directory
#              -rw------- (600) for files

Backup Considerations

Safe to backup:

  • settings.json (contains only GitLab URL)
  • ai-analysis-cache.json (contains analysis results)

DO NOT backup:

  • protected-token.dat (encrypted, machine-specific)
  • Keychain entries (macOS)
  • DPAPI encrypted data (Windows)

Multi-User Environments

Shared Servers

Problem: Multiple users on same server

Solution 1: Per-user configuration

  # Each user has own configuration
/home/user1/.gitlab-summary/  ← User 1
/home/user2/.gitlab-summary/  ← User 2

Solution 2: Service account

  # Create dedicated service account
sudo useradd -r -s /bin/bash gitlab-summary-svc

# Configure as service account
sudo su - gitlab-summary-svc
gitlab-summary token set --url https://gitlab.example.com

Shared Dashboards

Use Group Access Token:

  # Not personal token
# Create at: Group → Settings → Access Tokens

# Store on dashboard server
gitlab-summary token set --url https://gitlab.example.com

# Start as systemd service
sudo systemctl start gitlab-summary-dashboard

Restrict Access:

  • Use reverse proxy with authentication
  • Network-level access control
  • VPN requirement
  • SSO integration (via proxy)

Audit & Monitoring

GitLab Audit Logs

Monitor token usage in GitLab:

  1. Admin Area → Audit Events
  2. Group → Settings → Audit Events
  3. User → Audit Log

Look for:

  • API access patterns
  • Failed authentication attempts
  • Unusual access times
  • Access from unexpected IPs

Token Rotation

Regular Schedule:

  # Every 90 days
# 1. Create new token in GitLab
# 2. Update gitlab-summary
gitlab-summary token clear
gitlab-summary token set --url https://gitlab.example.com
# 3. Test
gitlab-summary pipelines --group test --since 1h
# 4. Revoke old token in GitLab

Compromise Response

If token is compromised:

Immediate Actions:

  # 1. Revoke token in GitLab immediately
GitLab → User Settings → Access Tokens → Revoke

# 2. Clear from all systems
gitlab-summary token clear

# 3. Review audit logs
# Check for unauthorized access

# 4. Create new token
# With new name/expiration

# 5. Update gitlab-summary
gitlab-summary token set --url https://gitlab.example.com

# 6. Notify security team
# If required by policy

Compliance Considerations

GDPR

gitlab-summary:

  • Does not collect personal data
  • Stores only GitLab URL and encrypted token locally
  • AI analysis may send job logs to GitHub (review logs for PII)

SOC 2

Controls:

  • Token encryption at rest ✅
  • Minimum privilege (read_api only) ✅
  • Audit trail (GitLab audit logs) ✅
  • Access control (file permissions) ✅

PCI DSS

Considerations:

  • Don’t log payment card data in CI/CD
  • Review job logs before AI analysis
  • Ensure tokens are not exposed in logs

Security Checklist

Before deploying gitlab-summary:

  • Token has only read_api scope
  • Token has expiration date set
  • HTTPS configured (not HTTP)
  • File permissions set correctly (700/600)
  • Using group token for shared access
  • Reviewed AI analysis privacy implications
  • Dashboard access restricted (if team deployment)
  • Rotation schedule established
  • Audit logging enabled in GitLab
  • Backup strategy excludes tokens
  • Team trained on security practices

Security Updates

Stay informed about security updates:

Reporting Security Issues

Found a security vulnerability?

DO NOT open a public GitHub issue.

DO:

  1. Email maintainer directly (check SECURITY.md if available)
  2. Include:
    • Vulnerability description
    • Steps to reproduce
    • Impact assessment
    • Suggested fix (if known)

See Also