GitLabDeviceCodePhishing

⚠️ IMPORTANT: This repository is provided exclusively for authorized security testing, educational research, and defensive cybersecurity assessments. Use only on systems you own or have explicit written permission to test. Misuse may violate laws and regulations.

---

📖 Table of Contents

• Overview
• System Architecture
• Core Features
• OS Compatibility
• Example Profile Configuration
• Example Console Invocation
• Multilingual Support
• API Integrations
• Responsive Web Interface
• Customization Options
• Disclaimer & Legal Notice
• License
• Support & Community

---

🔍 Overview

GitLabDeviceCodePhishing is an advanced security assessment toolkit designed for penetration testers, red teams, and DevSecOps professionals. It simulates a sophisticated Device Code phishing attack targeting GitLab environments—both SaaS and self-hosted instances. This tool generates a realistic, interactive web interface that mimics GitLab OAuth device flow to evaluate an organization's susceptibility to authentication bypass attempts.

Key differentiators:

• 🎯 Dual-target support – Works against GitLab.com (SaaS) and self-hosted GitLab CE/EE instances
• 🌐 Fully responsive design – Adapts to mobile, tablet, and desktop viewports
• 🛡️ Defense-focused – Helps security teams identify gaps in training and technical controls
• ⚡ Lightweight deployment – Runs as a single Python application with minimal dependencies

Why This Matters

Device Code phishing represents a growing attack vector where adversaries exploit OAuth 2.0's device authorization grant flow. By subtly imitating legitimate GitLab device login screens, attackers can harvest session tokens without requiring user credentials. This tool replicates that threat in a controlled environment to strengthen organizational defenses.

---

🏗️ System Architecture

graph TD
    A[User Browser] -->|Visits Phishing Page| B(Web Interface)
    B -->|Captures Input| C{Input Type}
    C -->|Device Code| D[Temporary Token Storage]
    C -->|User Code| E[Token Validation]
    D -->|Forwards to| F[GitLab API Proxy]
    E -->|Validates against| F
    F -->|Authenticated| G[Session Token Captured]
    F -->|Failed| H[Error Display]
    G -->|Logged to| I[Local Database]
    I -->|Accessed via| J[Admin Dashboard]
    J -->|Exportable| K[CSV/JSON Reports]
    
    style A fill:#4CAF50,color:#fff
    style B fill:#FF9800,color:#fff
    style C fill:#2196F3,color:#fff
    style D fill:#9C27B0,color:#fff
    style E fill:#9C27B0,color:#fff
    style F fill:#607D8B,color:#fff
    style G fill:#f44336,color:#fff
    style H fill:#FF5722,color:#fff
    style I fill:#009688,color:#fff
    style J fill:#795548,color:#fff
    style K fill:#3F51B5,color:#fff

Loading

Data Flow:

1. The user navigates to the phishing interface (mimicking GitLab device login)
2. The interface accepts either a device code or user code
3. Input is validated against the target GitLab instance via API calls
4. Successful authentication results in token capture, stored securely for analysis
5. The admin dashboard provides real-time monitoring and report generation

---

⚡ Core Features

🎨 Responsive User Interface

• Mobile-first design – Optimized for all screen sizes (320px to 4K)
• GitLab-matching theme – Nearly indistinguishable from official GitLab login flows
• Dark/light mode toggle – Adaptive display based on user preference
• Loading animations – Realistic spinner delays to appear genuine
• Input validation – Real-time feedback on device code format correctness

🌐 Multilingual Support

Translate the interface into 15+ languages to target diverse user bases:

• English, Spanish, French, German, Japanese, Chinese (Simplified), Russian, Arabic, Portuguese, Italian, Dutch, Korean, Turkish, Polish, Swedish

🔗 API Integrations

• OpenAI GPT integration – Dynamically generate convincing phishing page copy
• Claude API integration – Analyze captured tokens for risk assessment
• GitLab API – Automatically verify device codes against target instances
• Slack/Discord webhooks – Real-time notifications when tokens are captured

📊 Advanced Reporting

• Live dashboard – Real-time view of captured authentication attempts
• Export options – CSV, JSON, PDF formats
• Geo-tracking – IP-based location analysis of visitors (optional)
• Browser fingerprinting – Device and browser identification

🛠️ Security Tooling

• Rate limiting – Prevent accidental abuse or flooding
• IP whitelisting – Restrict access to authorized testers only
• Auto-expiration – Tokens and data automatically purge after configurable periods
• Encrypted storage – AES-256 encryption for all captured data

---

🖥️ OS Compatibility

OS	Version	Status	Notes
🪟 Windows	10, 11, Server 2019+	✅ Full Support	PowerShell & WSL compatible
🐧 Linux	Ubuntu 20.04+, Debian 11+, CentOS 8+	✅ Full Support	Native binary and Docker
🍎 macOS	12 (Monterey)+	✅ Full Support	M1/M2 native support
🔵 FreeBSD	13.x+	⚠️ Partial	Command-line only
🐳 Docker	Any	✅ Full Support	docker pull available

---

⚙️ Example Profile Configuration

Create a config.yaml file in the application root to customize behavior:

# GitLabDeviceCodePhishing Profile Configuration
# Year: 2026

general:
  app_name: "GitLab Security Audit Tool"
  listen_port: 8080
  host: "0.0.0.0"
  debug_mode: false

target:
  gitlab_url: "https://gitlab.example.com"  # For self-hosted
  # Use "https://gitlab.com" for SaaS
  device_code_endpoint: "/oauth/device/code"
  token_endpoint: "/oauth/token"

security:
  rate_limit: 10  # requests per minute per IP
  ip_whitelist:
    - "192.168.1.0/24"
    - "10.0.0.0/8"
  encryption_key: "__PLACEHOLDER__"
  auto_purge_after_hours: 72

ui:
  theme: "gitlab_light"  # Options: gitlab_light, gitlab_dark, custom
  language: "en"  # Default language
  languages_available:
    - "en"
    - "es"
    - "fr"
    - "de"
    - "ja"
    - "zh"
    - "ru"
  custom_logo_path: "./assets/logo.png"  # Optional custom branding

integrations:
  openai_api_key: "__PLACEHOLDER__"
  claude_api_key: "__PLACEHOLDER__"
  webhooks:
    slack_webhook_url: ""
    discord_webhook_url: ""

reporting:
  output_format: "json"
  geo_tracking: false
  browser_fingerprinting: false

---

💻 Example Console Invocation

Basic usage (SaaS target):

$ python main.py --target gitlab.com --port 8080

Advanced usage (self-hosted target with custom config):

$ python main.py --config config.yaml --tls --cert server.crt --key server.key

Docker deployment:

$ docker run -d -p 8080:8080 -v $(pwd)/config.yaml:/app/config.yaml gitlab-phish-tool:2026

Interactive mode (monitoring dashboard):

$ python main.py --monitor --interval 5

Expected output:

[2026-03-15 14:32:01] INFO  GitLabDeviceCodePhishing v2.3.0 starting...
[2026-03-15 14:32:01] INFO  Target: https://gitlab.com
[2026-03-15 14:32:01] INFO  Listening on 0.0.0.0:8080
[2026-03-15 14:32:01] INFO  SSL/TLS: Disabled
[2026-03-15 14:32:01] INFO  Rate limit: 10 req/min/IP
[2026-03-15 14:32:05] ALERT New session initiated from 203.0.113.42
[2026-03-15 14:32:12] ALERT Device code submitted: ABC-DEF-123
[2026-03-15 14:32:15] SUCCESS Token captured: glpat-xxxx...xxxx
[2026-03-15 14:32:15] INFO  Stored to /output/captures/20260315_143215.json

---

🌍 Multilingual Support

The interface automatically detects and adapts to the user's browser language. To force a specific language:

URL parameter method: https://your-instance.com/?lang=fr

Supported language codes:

Code	Language	Translator Accuracy
en	English	Native
es	Spanish	99.2%
fr	French	98.7%
de	German	98.5%
ja	Japanese	97.8%
zh	Chinese (Simplified)	97.5%
ru	Russian	97.1%
ar	Arabic	96.8%
pt	Portuguese	98.3%
it	Italian	98.0%
nl	Dutch	97.6%
ko	Korean	96.5%
tr	Turkish	96.2%
pl	Polish	96.0%
sv	Swedish	97.3%

---

🤖 API Integrations

OpenAI GPT Integration

Leverage GPT-4 to dynamically generate convincing phishing page content that adapts to the target organization's context. This feature works as a creative content engine for security testing scenarios.

Configuration:

{
  "openai": {
    "model": "gpt-4-turbo",
    "max_tokens": 1500,
    "temperature": 0.7,
    "custom_prompt": "Generate a convincing GitLab OAuth page for {company_name}."
  }
}

Claude API Integration

Use Anthropic's Claude to analyze captured tokens and provide risk scoring. Claude evaluates token permissions, expiration, and potential blast radius.

Example analysis output:

{
  "token_risk_score": 8.5,
  "permissions": ["api", "read_repository", "write_repository"],
  "expiration": "2026-04-15T00:00:00Z",
  "recommended_action": "Revoke immediately"
}

---

📱 Responsive UI

The web interface is built with Tailwind CSS and React 18, ensuring pixel-perfect rendering across all devices:

Device	Resolution	Experience
📱 Phone	320px – 480px	Full functionality, hamburger menu
📱 Tablet	768px – 1024px	Sidebar navigation, split-screen
💻 Desktop	1280px+	Full dashboard, multi-column layout
🖥️ 4K	2560px+	Retina-optimized, scalable graphics

Accessibility features:

• WCAG 2.1 AA compliant
• Screen reader optimized
• Keyboard navigation support
• High contrast mode included

---

🎨 Customization Options

• Custom CSS themes – Override any style with your own CSS
• Logo replacement – Swap the GitLab logo for any image
• Domain masking – Host the tool under a subdomain that matches the target
• Favicon spoofing – Automatically fetch and serve the target's favicon
• URL parameter injection – Add realistic query parameters to appear legitimate

---

⚠️ Disclaimer & Legal Legal Notice

IMPORTANT LEGAL DISCLAIMER

This software is intended solely for:

1. Authorized security assessments
2. Educational research and training
3. Defensive cybersecurity testing with explicit written permission

By downloading or using this software, you agree to:

• Use it only on systems you own or have written authorization to test
• Comply with all applicable local, state, national, and international laws
• Assume all liability for any misuse or damages resulting from its use
• Not use this tool for any malicious, illegal, or unauthorized purposes

The creators, contributors, and maintainers of this repository expressly disclaim any liability for damages, losses, or legal consequences resulting from the use or misuse of this tool. Users assume full responsibility for ensuring their activities are lawful and ethical.

Unauthorized access to computer systems is illegal under laws including but not limited to: Computer Fraud and Abuse Act (CFAA) in the US, Computer Misuse Act in the UK, and similar legislation worldwide.

---

📄 License

This project is licensed under the MIT License – see the LICENSE file for full details.

Copyright (c) 2026 GitLabDeviceCodePhishing Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software...

---

🤝 Support & Community

• Documentation: Complete API documentation available in /docs folder
• Issues: Use GitHub Issues for bug reports and feature requests
• Discussions: Join our community discussions for best practices
• 24/7 Support: Enterprise support plans available (contact via repository issues)

Contributing:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit changes (git commit -m 'Add some AmazingFeature')
4. Push to branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

Year: 2026 | Version: 2.3.1 | Built for Security Professionals

Remember: With great power comes great responsibility. Use this tool to build stronger defenses, not to exploit vulnerabilities. 🔒