Security

Open Source — GitScrum CLI is open source under the MIT license. Available on GitHub and all major package managers. Built for developers — Tasks, timers, sprints, and analytics in your terminal. Git-aware. CI/CD ready.

The GitScrum CLI is designed around the principle of least privilege. Here's how we keep your credentials safe.

Authentication Flow

The CLI uses OAuth 2.0 Device Authorization Grant (RFC 8628), the industry standard for CLI authentication.

How It Works

1. CLI requests device code — No secrets are exchanged yet
2. You authorize in browser — Login happens in your browser, not the CLI
3. CLI receives token — Only after browser authorization
4. Token stored locally — Encrypted on your machine, nowhere else

┌─────────────┐                    ┌─────────────┐
│   Terminal  │ ── device code ──► │  GitScrum   │
│             │ ◄── verification ─ │   OAuth     │
└─────────────┘         URL        └─────────────┘
       │                                   ▲
       │ Open browser                      │
       ▼                                   │
┌─────────────┐                    ┌─────────────┐
│   Browser   │ ── login/MFA ────► │  GitScrum   │
└─────────────┘     authorize      │   Login     │
                                   └─────────────┘
       │
       │ Token issued
       ▼
┌─────────────┐
│   Terminal  │  ← Access granted
└─────────────┘

Why Device Flow?

• No password handling. The CLI never sees your password.
• MFA compatible. Works with any 2FA method.
• Revocable. Revoke CLI access without changing your password.
• Browser security. Leverage your browser's security features (password managers, biometrics).

Token Storage

OAuth tokens are stored locally on your machine:

File Permissions

The CLI sets file permissions to 0600 (owner read/write only):

$ ls -la ~/.gitscrum/token.json
-rw------- 1 user user 256 Feb 7 09:00 token.json

On Windows, the file inherits the user's home directory permissions.

Token Contents

{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "token_type": "Bearer",
  "expires_at": "2026-02-08T09:00:00Z"
}

Tokens are not encrypted at rest — they rely on filesystem permissions. If you need additional protection, use full-disk encryption.

Token Lifecycle

Automatic Refresh

The CLI automatically refreshes access tokens before they expire. You don't need to re-authenticate unless:

• You explicitly run gitscrum auth logout
• The refresh token expires (7 days of inactivity)
• You revoke CLI access in GitScrum settings

CI/CD Security

Environment Variable Authentication

For headless environments, use the GITSCRUMACCESSTOKEN environment variable:

export GITSCRUM_ACCESS_TOKEN="your-oauth-access-token"

Best Practices

1. Use secrets management. Never hardcode tokens in code or config files.
2. Rotate tokens. Periodically re-authenticate to get fresh tokens.
3. Limit scope. Use project-specific tokens when possible.
4. Audit access. Review OAuth applications in GitScrum settings.

Platform-Specific Secrets

Example: GitHub Actions

env:
  GITSCRUM_ACCESS_TOKEN: ${{ secrets.GITSCRUM_ACCESS_TOKEN }}

Never log the token:

# DON'T DO THIS
- run: echo $GITSCRUM_ACCESS_TOKEN  # Exposes token in logs

Network Security

HTTPS Only

All CLI communication uses HTTPS with TLS 1.2 minimum. The CLI refuses to connect over HTTP.

Endpoints

The CLI connects to:

Proxy Support

The CLI respects standard proxy environment variables:

export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

Revoking Access

From CLI

gitscrum auth logout

This removes local tokens. For complete revocation:

From GitScrum Web

1. Go to GitScrum Settings
2. Navigate to Connected Apps
3. Revoke the CLI application

This invalidates all tokens issued to the CLI.

Vulnerability Reporting

Found a security issue? Report privately:

• Email: security@gitscrum.com
• GitHub: Private vulnerability reporting

Please don't open public issues for security vulnerabilities.

Security Checklist

Local Development

• [ ] Token file has restricted permissions (0600)
• [ ] Using full-disk encryption if required
• [ ] Not sharing ~/.gitscrum/ directory

CI/CD

• [ ] Token stored as secret, not in code
• [ ] Token not logged in pipeline output
• [ ] Regular token rotation
• [ ] Access reviewed periodically

Enterprise

• [ ] OAuth application approved by security team
• [ ] Proxy configured if required
• [ ] Firewall allows GitScrum endpoints