Security Features

YouTrack CLI includes comprehensive security enhancements to protect user credentials and provide audit capabilities for enterprise environments.

Overview

The security features include:

  • Command Audit Logging: Track all CLI commands with timestamps

  • Credential Encryption: Secure storage of tokens and credentials

  • Token Expiration Warnings: Proactive alerts before tokens expire

  • Sensitive Data Masking: Automatic masking of credentials in output and logs

Command Audit Logging

All CLI commands are automatically logged with timestamps for security auditing and compliance purposes.

Features:

  • Logs command names, arguments, timestamps, and execution status

  • Automatically masks sensitive information (tokens, passwords, API keys)

  • Configurable storage limits (default: 1000 entries)

  • JSON export capability for integration with external systems

Usage:

View recent audit entries:

yt security audit

View more entries:

yt security audit --limit 100

Export as JSON:

yt security audit --format json

Clear audit log:

yt security clear-audit

Configuration:

Audit logging can be disabled using the --secure flag:

yt --secure issues list

This prevents command logging while maintaining other security features.

Credential Encryption

Credentials are encrypted at rest using industry-standard encryption and the system keyring where available.

Features:

  • AES encryption using the cryptography library

  • System keyring integration (Keychain on macOS, Credential Manager on Windows, Secret Service on Linux)

  • Automatic fallback to encrypted file storage

  • Secure key generation and management

Storage Locations:

The CLI attempts to store credentials in the following order:

  1. System Keyring (most secure) - Uses OS-provided credential storage

  2. Encrypted File (fallback) - ~/.local/share/youtrack-cli/ with encryption

  3. Plain Text File (legacy) - ~/.config/youtrack-cli/.env for compatibility

Usage:

Credentials are automatically encrypted when using yt auth login:

yt auth login

The system will indicate the storage method used:

  • ✅ Green: Stored securely in keyring

  • ⚠️ Yellow: Stored in encrypted file (keyring unavailable)

Environment Variables:

For CI/CD environments, you can disable keyring and use environment variables:

export YOUTRACK_BASE_URL="https://company.youtrack.cloud"
export YOUTRACK_TOKEN="your-api-token"

Token Expiration Management

The CLI proactively monitors token expiration and provides warnings before tokens expire.

Features:

  • Automatic expiration checking on credential load

  • Configurable warning period (default: 7 days)

  • Color-coded status indicators

  • Manual token status checking

Usage:

Check current token status:

yt security token-status

The output will show:

  • 🟢 Valid: Token is current and not expiring soon

  • 🟡 Expiring: Token expires within the warning period

  • 🔴 Expired: Token has expired and needs renewal

  • ✅ Permanent: Token is permanent and does not expire

  • ⚪ Unknown: Expiration date not available

Setting Token Expiry:

When creating tokens in YouTrack, note the expiration date. The CLI will automatically detect JWT token expiration where possible.

SSL Verification Warnings

The CLI monitors SSL certificate verification settings and issues security warnings when SSL verification is disabled.

Features:

  • Automatic detection of SSL verification bypass via environment variables

  • Security warnings displayed when SSL verification is disabled

  • Audit logging of SSL configuration changes for compliance tracking

  • Clear messaging about security implications

Usage:

By default, SSL verification is enabled and the CLI will verify certificates for all HTTPS connections to YouTrack:

# SSL verification enabled (default, secure)
yt issues list

To disable SSL verification (for development environments only), set the environment variable:

# SSL verification disabled (INSECURE - development only)
export YOUTRACK_VERIFY_SSL=false
yt issues list

When SSL verification is disabled, you will see a security warning:

⚠️  SSL verification is DISABLED. This is insecure and should only be used in development.

Security Implications:

Disabling SSL verification exposes your connection to man-in-the-middle attacks where:

  • Attackers can intercept and read your API tokens and data

  • Malicious actors can modify requests and responses

  • Your YouTrack credentials and data may be compromised

Audit Logging:

All SSL configuration changes are automatically logged in the audit trail:

yt security audit

This includes entries for:

  • SSL verification status (enabled/disabled)

  • Environment variable values

  • Timestamps of configuration changes

Best Practices:

  1. Never disable SSL verification in production environments

  2. Only use YOUTRACK_VERIFY_SSL=false for local development with self-signed certificates

  3. Monitor audit logs for unexpected SSL verification changes

  4. Use proper CA-signed certificates in all production environments

  5. Consider using organizational certificate authorities for internal systems

Sensitive Data Masking

All output and logs automatically mask sensitive information to prevent credential exposure.

Masked Patterns:

  • API tokens and bearer tokens

  • Passwords and passphrases

  • API keys and secrets

  • Authorization headers

Example Output:

Before masking:

Authorization: Bearer perm:abc123.def456.ghi789
token=secret_api_key_here

After masking:

Authorization: Bearer ***MASKED***
token=***MASKED***

Security Best Practices

For Individual Users:

  1. Use System Keyring: Allow the CLI to use your system’s credential manager

  2. Monitor Token Expiry: Regularly check yt security token-status

  3. Review Audit Logs: Periodically check yt security audit for unexpected activity

  4. Secure Environment: Keep your system updated and use endpoint protection

For Enterprise Environments:

  1. Centralized Audit Collection: Export audit logs to SIEM systems:

    yt security audit --format json > audit-export.json

  2. Token Lifecycle Management:

    • Set appropriate token expiration periods

    • Implement token rotation policies

    • Monitor for expired tokens across teams

  3. Access Control:

    • Use principle of least privilege for token permissions

    • Regularly review and revoke unused tokens

    • Implement approval workflows for sensitive operations

  4. Compliance Integration:

    • Configure automated audit log collection

    • Set up alerts for failed authentication attempts

    • Maintain audit trails for compliance reporting

For CI/CD Pipelines:

  1. Environment Variables: Use secure environment variable storage:

    # In your CI/CD system
YOUTRACK_BASE_URL=https://company.youtrack.cloud
YOUTRACK_TOKEN=ci_token_here

  2. Secure Flag: Use --secure to prevent logging in automated environments:

    yt --secure issues create PROJECT-123 "Automated issue"

  3. Token Scoping: Create dedicated CI tokens with minimal required permissions

  4. Secret Rotation: Implement regular token rotation for automated systems

Configuration Options

Security features can be configured through environment variables or the configuration file.

Environment Variables:

# Disable audit logging
export YT_AUDIT_LOGGING=false

# Disable credential encryption
export YT_CREDENTIAL_ENCRYPTION=false

# Disable token expiration warnings
export YT_TOKEN_WARNINGS=false

# Set custom warning period (days)
export YT_TOKEN_WARNING_DAYS=14

# Set audit log size limit
export YT_AUDIT_MAX_ENTRIES=2000

Configuration File:

Add to ~/.config/youtrack-cli/.env:

YT_AUDIT_LOGGING=true
YT_CREDENTIAL_ENCRYPTION=true
YT_TOKEN_WARNINGS=true
YT_TOKEN_WARNING_DAYS=7
YT_AUDIT_MAX_ENTRIES=1000

Troubleshooting

Keyring Issues:

If keyring storage fails:

  1. Install keyring backends:

    # Linux
sudo apt-get install gnome-keyring python3-keyring

# macOS (usually available by default)
pip install keyring

# Windows (usually available by default)
pip install keyring

  2. Check keyring status:

    python -c "import keyring; print(keyring.get_keyring())"

  3. Fall back to file storage if needed - the CLI will automatically handle this

Audit Log Issues:

If audit logging fails:

  1. Check permissions on log directory:

    ls -la ~/.local/share/youtrack-cli/

  2. Manually create directory if needed:

    mkdir -p ~/.local/share/youtrack-cli/

  3. Clear corrupted audit log:

    yt security clear-audit --force

Token Expiration Issues:

If token warnings are incorrect:

  1. Update token with correct expiry:

    yt auth token --update

  2. Check system clock synchronization

  3. Verify token format and YouTrack version compatibility

Security Considerations

Limitations:

  • Keyring availability varies by system configuration

  • Audit logs are stored locally (consider centralized collection for enterprises)

  • Token expiration detection depends on YouTrack API and token format

  • File permissions rely on operating system security

Recommendations:

  • Regularly backup encrypted credential files

  • Monitor system security updates

  • Use dedicated service accounts for automation

  • Implement network-level security controls

  • Consider using VPN or private networks for YouTrack access

Compliance:

The security features support various compliance frameworks:

  • SOC 2: Audit logging and access controls

  • ISO 27001: Information security management

  • GDPR: Data protection and audit trails

  • PCI DSS: Secure credential handling

For specific compliance requirements, consult with your security team to configure appropriate controls and monitoring.