token_checker.py

#!/usr/bin/env python3
"""
GitHub Token Capability Auditor

Analyzes GitHub Personal Access Tokens to determine their permissions,
accessible resources, and potential security implications.

Usage:
    python token_checker.py <token>
    python token_checker.py  # reads from GITHUB_TOKEN env var
"""

import os
import sys
import json
import argparse
from typing import Optional
from dataclasses import dataclass, field
from datetime import datetime

try:
    import requests
except ImportError:
    print("Error: requests library required. Install with: pip install requests")
    sys.exit(1)


@dataclass
class TokenReport:
    """Structured report of token capabilities."""
    token_type: str = "unknown"
    scopes: list = field(default_factory=list)
    user: Optional[dict] = None
    orgs: list = field(default_factory=list)
    repos: list = field(default_factory=list)
    packages: list = field(default_factory=list)
    rate_limit: Optional[dict] = None
    errors: list = field(default_factory=list)
    warnings: list = field(default_factory=list)


class TokenChecker:
    """Audits GitHub token capabilities."""

    API_BASE = "https://api.github.com"

    def __init__(self, token: str):
        self.token = token
        self.headers = {
            "Authorization": f"token {token}",
            "Accept": "application/vnd.github+json",
            "X-GitHub-Api-Version": "2022-11-28"
        }
        self.report = TokenReport()

    def _request(self, endpoint: str, method: str = "GET", **kwargs) -> tuple[Optional[dict], dict]:
        """Make API request and return (json_response, headers)."""
        url = f"{self.API_BASE}{endpoint}"
        try:
            resp = requests.request(method, url, headers=self.headers, timeout=30, **kwargs)
            headers = dict(resp.headers)
            if resp.status_code == 200:
                return resp.json(), headers
            elif resp.status_code == 401:
                self.report.errors.append(f"Authentication failed for {endpoint}")
                return None, headers
            elif resp.status_code == 403:
                self.report.warnings.append(f"Access denied for {endpoint}")
                return None, headers
            elif resp.status_code == 404:
                return None, headers
            else:
                self.report.warnings.append(f"{endpoint} returned {resp.status_code}")
                return None, headers
        except requests.RequestException as e:
            self.report.errors.append(f"Request failed for {endpoint}: {e}")
            return None, {}

    def check_token_type_and_scopes(self):
        """Determine token type and OAuth scopes."""
        data, headers = self._request("/user")

        # Check OAuth scopes from response headers
        scopes = headers.get("X-OAuth-Scopes", "")
        if scopes:
            self.report.scopes = [s.strip() for s in scopes.split(",") if s.strip()]

        # Determine token type
        if "X-OAuth-Scopes" in headers:
            self.report.token_type = "personal_access_token"
        elif data:
            # Fine-grained tokens don't have X-OAuth-Scopes
            self.report.token_type = "fine_grained_token"
        else:
            self.report.token_type = "invalid_or_expired"

        if data:
            self.report.user = {
                "login": data.get("login"),
                "id": data.get("id"),
                "name": data.get("name"),
                "email": data.get("email"),
                "type": data.get("type"),
                "site_admin": data.get("site_admin", False)
            }

    def check_rate_limit(self):
        """Check rate limit status."""
        data, _ = self._request("/rate_limit")
        if data:
            self.report.rate_limit = {
                "core": data.get("resources", {}).get("core", {}),
                "search": data.get("resources", {}).get("search", {}),
                "graphql": data.get("resources", {}).get("graphql", {})
            }

    def check_organizations(self):
        """List accessible organizations."""
        data, _ = self._request("/user/orgs?per_page=100")
        if data:
            for org in data:
                org_info = {
                    "login": org.get("login"),
                    "id": org.get("id"),
                    "role": "member"
                }
                # Check if admin
                membership, _ = self._request(f"/user/memberships/orgs/{org.get('login')}")
                if membership:
                    org_info["role"] = membership.get("role", "member")
                    org_info["state"] = membership.get("state")

                self.report.orgs.append(org_info)

    def check_repositories(self):
        """List accessible repositories with permission levels."""
        # Get repos the token can access
        data, _ = self._request("/user/repos?per_page=100&affiliation=owner,collaborator,organization_member")
        if data:
            for repo in data[:50]:  # Limit to 50 for performance
                repo_info = {
                    "full_name": repo.get("full_name"),
                    "private": repo.get("private", False),
                    "permissions": repo.get("permissions", {}),
                    "visibility": repo.get("visibility"),
                }
                self.report.repos.append(repo_info)

    def check_packages(self):
        """Check access to GitHub Container Registry / Packages."""
        # Check user packages
        data, _ = self._request("/user/packages?package_type=container&per_page=100")
        if data:
            for pkg in data:
                self.report.packages.append({
                    "name": pkg.get("name"),
                    "package_type": pkg.get("package_type"),
                    "visibility": pkg.get("visibility"),
                    "owner": pkg.get("owner", {}).get("login")
                })

        # Check org packages
        for org in self.report.orgs:
            org_login = org.get("login")
            data, _ = self._request(f"/orgs/{org_login}/packages?package_type=container&per_page=100")
            if data:
                for pkg in data:
                    self.report.packages.append({
                        "name": pkg.get("name"),
                        "package_type": pkg.get("package_type"),
                        "visibility": pkg.get("visibility"),
                        "owner": org_login
                    })

    def check_specific_org_repos(self, org: str):
        """Check access to a specific organization's repos."""
        data, _ = self._request(f"/orgs/{org}/repos?per_page=100")
        if data:
            print(f"\n  Accessible repos in {org}:")
            for repo in data:
                perms = repo.get("permissions", {})
                perm_str = []
                if perms.get("admin"):
                    perm_str.append("admin")
                if perms.get("push"):
                    perm_str.append("push")
                if perms.get("pull"):
                    perm_str.append("pull")
                print(f"    - {repo.get('name')}: {', '.join(perm_str) or 'read-only'}")

    def check_write_capabilities(self):
        """Test what write operations might be possible."""
        capabilities = []

        # Check if we can create repos
        if "repo" in self.report.scopes or "public_repo" in self.report.scopes:
            capabilities.append("create_repos")

        # Check if we can write packages
        if "write:packages" in self.report.scopes:
            capabilities.append("write_packages")
        if "delete:packages" in self.report.scopes:
            capabilities.append("delete_packages")

        # Check workflow permissions
        if "workflow" in self.report.scopes:
            capabilities.append("modify_workflows")

        # Check admin permissions
        if "admin:org" in self.report.scopes:
            capabilities.append("admin_orgs")
        if "admin:repo_hook" in self.report.scopes:
            capabilities.append("manage_webhooks")

        # Check GPG/SSH key permissions
        if "admin:gpg_key" in self.report.scopes:
            capabilities.append("manage_gpg_keys")
        if "admin:public_key" in self.report.scopes:
            capabilities.append("manage_ssh_keys")

        return capabilities

    def run_full_audit(self):
        """Run complete token audit."""
        print("=" * 60)
        print("GitHub Token Capability Audit")
        print("=" * 60)
        print(f"Timestamp: {datetime.now().isoformat()}")
        print()

        print("[1/5] Checking token type and scopes...")
        self.check_token_type_and_scopes()

        print("[2/5] Checking rate limits...")
        self.check_rate_limit()

        print("[3/5] Checking organization access...")
        self.check_organizations()

        print("[4/5] Checking repository access...")
        self.check_repositories()

        print("[5/5] Checking package/container access...")
        self.check_packages()

        print()
        self.print_report()

    def print_report(self):
        """Print formatted report."""
        print("=" * 60)
        print("AUDIT RESULTS")
        print("=" * 60)

        # Token info
        print(f"\nToken Type: {self.report.token_type}")

        if self.report.user:
            print(f"\nAuthenticated User:")
            print(f"  Login: {self.report.user.get('login')}")
            print(f"  ID: {self.report.user.get('id')}")
            print(f"  Name: {self.report.user.get('name')}")
            print(f"  Type: {self.report.user.get('type')}")
            print(f"  Site Admin: {self.report.user.get('site_admin')}")

        # Scopes
        if self.report.scopes:
            print(f"\nOAuth Scopes ({len(self.report.scopes)}):")
            for scope in sorted(self.report.scopes):
                print(f"  - {scope}")
        else:
            print("\nOAuth Scopes: None (fine-grained token or no scopes)")

        # Capabilities
        capabilities = self.check_write_capabilities()
        if capabilities:
            print(f"\nWrite Capabilities:")
            for cap in capabilities:
                print(f"  - {cap}")

        # Organizations
        if self.report.orgs:
            print(f"\nOrganization Access ({len(self.report.orgs)}):")
            for org in self.report.orgs:
                print(f"  - {org.get('login')} (role: {org.get('role')})")

        # Repositories summary
        if self.report.repos:
            private_repos = [r for r in self.report.repos if r.get("private")]
            admin_repos = [r for r in self.report.repos if r.get("permissions", {}).get("admin")]
            push_repos = [r for r in self.report.repos if r.get("permissions", {}).get("push")]

            print(f"\nRepository Access ({len(self.report.repos)} sampled):")
            print(f"  - Private repos: {len(private_repos)}")
            print(f"  - Admin access: {len(admin_repos)}")
            print(f"  - Push access: {len(push_repos)}")

            if admin_repos:
                print(f"\n  Repos with admin access:")
                for repo in admin_repos[:10]:
                    print(f"    - {repo.get('full_name')}")
                if len(admin_repos) > 10:
                    print(f"    ... and {len(admin_repos) - 10} more")

        # Packages
        if self.report.packages:
            print(f"\nPackage/Container Access ({len(self.report.packages)}):")
            for pkg in self.report.packages[:10]:
                print(f"  - {pkg.get('owner')}/{pkg.get('name')} ({pkg.get('visibility')})")
            if len(self.report.packages) > 10:
                print(f"  ... and {len(self.report.packages) - 10} more")

        # Rate limit
        if self.report.rate_limit:
            core = self.report.rate_limit.get("core", {})
            print(f"\nRate Limit Status:")
            print(f"  Core: {core.get('remaining')}/{core.get('limit')}")

        # Warnings and errors
        if self.report.warnings:
            print(f"\nWarnings ({len(self.report.warnings)}):")
            for w in self.report.warnings[:5]:
                print(f"  - {w}")

        if self.report.errors:
            print(f"\nErrors ({len(self.report.errors)}):")
            for e in self.report.errors:
                print(f"  - {e}")

        # Security recommendations
        print("\n" + "=" * 60)
        print("SECURITY RECOMMENDATIONS")
        print("=" * 60)

        if "repo" in self.report.scopes:
            print("⚠️  Token has 'repo' scope - full access to all repositories")
        if "admin:org" in self.report.scopes:
            print("⚠️  Token has 'admin:org' scope - can modify organization settings")
        if "write:packages" in self.report.scopes:
            print("⚠️  Token can push to container registry")
        if "delete:packages" in self.report.scopes:
            print("🚨 Token can DELETE packages - high risk")
        if "workflow" in self.report.scopes:
            print("⚠️  Token can modify GitHub Actions workflows")
        if self.report.user and self.report.user.get("site_admin"):
            print("🚨 Token belongs to a GitHub site admin!")

        print()

    def to_json(self) -> str:
        """Export report as JSON."""
        return json.dumps({
            "token_type": self.report.token_type,
            "scopes": self.report.scopes,
            "user": self.report.user,
            "orgs": self.report.orgs,
            "repos": self.report.repos,
            "packages": self.report.packages,
            "rate_limit": self.report.rate_limit,
            "warnings": self.report.warnings,
            "errors": self.report.errors,
            "capabilities": self.check_write_capabilities()
        }, indent=2)


def main():
    parser = argparse.ArgumentParser(
        description="Audit GitHub token capabilities",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Examples:
    python token_checker.py ghp_xxxxx
    python token_checker.py --json ghp_xxxxx > report.json
    GITHUB_TOKEN=ghp_xxxxx python token_checker.py

    # Check specific org access
    python token_checker.py --org Zenith-Foundation ghp_xxxxx
        """
    )
    parser.add_argument("token", nargs="?", help="GitHub token (or set GITHUB_TOKEN env var)")
    parser.add_argument("--json", action="store_true", help="Output as JSON")
    parser.add_argument("--org", help="Check access to specific organization")

    args = parser.parse_args()

    token = args.token or os.environ.get("GITHUB_TOKEN")
    if not token:
        print("Error: No token provided. Pass as argument or set GITHUB_TOKEN env var.")
        sys.exit(1)

    checker = TokenChecker(token)

    if args.org:
        # Quick org check mode
        checker.check_token_type_and_scopes()
        print(f"Checking access to {args.org}...")
        checker.check_specific_org_repos(args.org)
    elif args.json:
        checker.check_token_type_and_scopes()
        checker.check_rate_limit()
        checker.check_organizations()
        checker.check_repositories()
        checker.check_packages()
        print(checker.to_json())
    else:
        checker.run_full_audit()


if __name__ == "__main__":
    main()