Security Guidelines for Sentinel CI

Overview

Sentinel CI handles sensitive CI/CD data including build logs, test results, and potentially credentials. This document outlines security best practices for deploying and using Sentinel CI safely.

🔒 Never Commit These Items

Credentials & Tokens: - CI/CD API tokens (Jenkins, GitHub, GitLab) - SSH keys - AWS access keys / secret keys - Database passwords - Service account credentials - OAuth tokens - Personal access tokens (PATs)

Configuration Files: - .env files - secrets.json - credentials.yaml - Any file ending in _token, _key, _secret

Internal Information: - Internal URLs and hostnames - IP addresses - Internal network configurations - Organization-specific data

✅ Safe Practices

1. Environment Variables

Always use environment variables for sensitive data:

# .env file (NEVER commit this)
JENKINS_URL=https://jenkins.example.com
JENKINS_TOKEN=user:api_token_here
GITHUB_TOKEN=ghp_xxxxxxxxxxxx
GITLAB_TOKEN=glpat-xxxxxxxxxxxx

Load in Python:

import os
from dotenv import load_dotenv

load_dotenv()

jenkins_url = os.getenv('JENKINS_URL')
jenkins_token = os.getenv('JENKINS_TOKEN')

2. Configuration Files

Use a template approach:

# config.example.yaml (committed)
jenkins:
  url: "https://jenkins.example.com"
  token: "${JENKINS_TOKEN}"  # Reference environment variable

# config.yaml (in .gitignore)
jenkins:
  url: "https://jenkins.mycompany.com"
  token: "user:actual_token_here"

3. Secret Redaction

Sentinel CI includes automatic secret redaction. Verify it's working:

from shared.redaction.redactor import SecretRedactor

redactor = SecretRedactor()
log = "password=secret123 token=abc-def-ghi"
redacted = redactor.redact(log)
print(redacted)  # Should show [REDACTED]

Patterns automatically redacted: - API keys (api_key=..., apikey:...) - Passwords (password=..., pwd=...) - Tokens (token=..., bearer ...) - AWS credentials (AKIA..., aws_secret_access_key) - Private keys (-----BEGIN PRIVATE KEY-----) - Email addresses - Credit card numbers - SSH keys - Database URLs with credentials - Generic secrets (secret=...)

4. Read-Only Operations

Sentinel CI is designed for read-only access: - Does not trigger builds - Does not modify configurations - Does not delete data - Only fetches and analyzes existing data

Use read-only tokens when possible:

Jenkins:

# Create a read-only user with:
# - Overall/Read
# - Job/Read
# - Job/Workspace

GitHub:

# Use fine-grained PATs with:
# - Actions: Read-only
# - Metadata: Read-only

GitLab:

# Create access token with:
# - read_api scope only
# - No write permissions

🔐 Token Management

Creating Tokens

Jenkins: 1. Go to User → Configure → API Token 2. Click "Add new Token" 3. Give it a descriptive name: "sentinel-ci-readonly" 4. Copy token immediately (shown only once) 5. Format: username:token

GitHub: 1. Settings → Developer settings → Personal access tokens → Fine-grained tokens 2. Select repository access 3. Permissions: Actions (read), Contents (read), Metadata (read) 4. Generate token 5. Format: ghp_xxxxxxxxxxxx

GitLab: 1. User Settings → Access Tokens 2. Name: "sentinel-ci" 3. Scopes: read_api 4. Create token 5. Format: glpat-xxxxxxxxxxxx

Token Rotation

Rotate tokens regularly (every 90 days):

# 1. Generate new token in CI platform
# 2. Update environment variable
export JENKINS_TOKEN="user:new_token_here"

# 3. Restart Sentinel CI
# 4. Verify functionality
# 5. Revoke old token

Token Storage

Local Development:

# Store in .env file (gitignored)
echo "JENKINS_TOKEN=user:token" >> .env

Production: - Use secret management: AWS Secrets Manager, HashiCorp Vault, Azure Key Vault - Use environment variables in container orchestration (Kubernetes secrets) - Never hardcode in Dockerfiles or config files

🛡️ Deployment Security

Network Security

Restrict access:

# Docker Compose example
services:
  sentinel-ci:
    ports:
      - "127.0.0.1:8000:8000"  # Only localhost

Use VPN or private network: - Deploy within corporate VPN - Use private subnets in cloud - Enable firewall rules

Authentication

Add authentication layer:

# Example: Add API key authentication
from functools import wraps
from flask import request

def require_api_key(f):
    @wraps(f)
    def decorated(*args, **kwargs):
        api_key = request.headers.get('X-API-Key')
        if api_key != os.getenv('SENTINEL_API_KEY'):
            return {'error': 'Unauthorized'}, 401
        return f(*args, **kwargs)
    return decorated

Audit Logging

Enable audit logging:

import logging

# Configure audit logger
audit_logger = logging.getLogger('sentinel_ci.audit')
audit_logger.setLevel(logging.INFO)

handler = logging.FileHandler('audit.log')
handler.setFormatter(logging.Formatter(
    '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
))
audit_logger.addHandler(handler)

# Log all API calls
def log_api_call(user, action, resource):
    audit_logger.info(f"User={user} Action={action} Resource={resource}")

🚨 Incident Response

If Credentials Are Exposed

Immediate actions:

1. Revoke compromised credentials in CI platform
2. Generate new credentials
3. Update environment variables
4. Rotate related secrets (if they share passwords)
5. Review audit logs for unauthorized access
6. Check git history for exposure:

   git log -p | grep -i "token\|password\|secret"
   

7. Use BFG Repo-Cleaner to remove from history:

   bfg --replace-text passwords.txt repo.git
   git push --force
   

If Public Repository Exposed

Actions:

1. Make repository private immediately
2. Rotate all credentials mentioned in commits
3. Review all forks (they may have copies)
4. Contact GitHub to remove cached versions
5. Enable GitHub secret scanning alerts
6. Add pre-commit hooks to prevent future exposure

🔍 Security Checklist

Before deploying to production:

• [ ] All credentials in environment variables
• [ ] .env file in .gitignore
• [ ] No hardcoded URLs or tokens in code
• [ ] Read-only tokens configured
• [ ] Secret redaction tested and working
• [ ] Audit logging enabled
• [ ] Network access restricted
• [ ] Authentication layer added
• [ ] Token rotation schedule defined
• [ ] Incident response plan documented
• [ ] Security scan completed (ruff, bandit)
• [ ] Dependency vulnerabilities checked (pip-audit)

🛠️ Security Tools

Scan for secrets:

# GitLeaks
gitleaks detect --source . --verbose

# TruffleHog
trufflehog git file://. --only-verified

Dependency scanning:

pip install pip-audit
pip-audit

Static analysis:

pip install bandit
bandit -r sentinel_ci/ shared/ mcps/

📞 Reporting Security Issues

DO NOT open public issues for security vulnerabilities.

Instead: 1. Email security@example.com 2. Include: - Description of vulnerability - Steps to reproduce - Potential impact - Suggested fix (if any) 3. Allow 90 days for response before public disclosure

📚 Additional Resources

• OWASP Top 10
• GitHub Security Best Practices
• CIS Benchmarks
• NIST Cybersecurity Framework

License

This security documentation is provided as-is without warranty. Always consult with your security team before deployment.